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
POSTrequests 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
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 exactlyJSON.stringify(body.data) using your webhook secret. It does not sign the complete envelope.
Acknowledge and process safely
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.
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
eventTypeagainst 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.

