Skip to main content
FossaPay sends webhook events when asynchronous financial operations change state. Use them for fast updates, but retain API-based reconciliation because delivery failure and transaction failure are different conditions.

Configure an endpoint

Add a public HTTPS endpoint from Dashboard → Settings → Webhooks, then securely store the generated secret. Every active webhook configured for your merchant receives applicable merchant events; event-by-event subscription filtering is not currently part of the public integration. Your endpoint should:
  • accept POST requests over HTTPS;
  • verify the signature before trusting the event;
  • return a 2xx response quickly;
  • queue business processing outside the request;
  • tolerate duplicate and out-of-order delivery.

Delivery envelope

The fields inside data depend on the event type. Build handlers around stable identifiers and the event’s documented payload rather than assuming all event types share one transaction shape.

Delivery headers

HTTP header names are case-insensitive.

Verify the signature

FossaPay computes HMAC-SHA256 over exactly JSON.stringify(body.data) using your webhook secret. It does not sign the complete envelope.
Preserve the parsed data key order when re-serializing in another language. Do not pretty-print it, sort its keys, or include eventId, eventType, or timestamp in the signed string.

Acknowledge and process safely

Place a unique constraint on eventId. Within your worker, make each financial state transition idempotent using the relevant transaction, checkout, payout, or reference identifier too.

Event catalogue

See Webhook Events for event-specific examples.

Retries and delivery status

Any non-2xx response, network error, DNS failure, or timeout marks that delivery attempt as failed. FossaPay schedules up to five retries with exponential backoff from five minutes: approximately 5, 10, 20, 40, and 80 minutes. A background worker checks due deliveries every five minutes, so actual delivery can occur slightly later.
A later successful retry sets the webhook delivery to delivered. It does not alter the underlying financial transaction, which may already be successful.
Use the dashboard webhook event log to inspect response status, error messages, retry count, and delivery state, and to retry an eligible failed event. Even with retries, your application should periodically reconcile important pending operations through their GET endpoints.

Event-specific reconciliation

Security and operations

  • Keep webhook secrets out of source control, client applications, and logs.
  • Reject an invalid or missing signature.
  • Rotate a secret if it may have been exposed, then update your receiver atomically.
  • Validate eventType against an allowlist and ignore unknown events safely.
  • Store the original envelope for audit with appropriate encryption and retention controls.
  • Monitor non-2xx rates and queue latency.
  • Do not rely on source-IP allowlisting as a substitute for HMAC verification.

Testing

There is no public webhook simulation endpoint. Test the handler locally with a fixture signed by the same algorithm, then perform a controlled production operation. Confirm signature verification, duplicate handling, queue processing, and reconciliation before processing regular volume.

API reference

Webhook overview

Delivery structure and verification reference.

Webhook events

Event names and payload examples.