Configure your endpoint
Set your callback URL in the bluSwap dashboard before processing live transactions. See Collections webhooks and Payouts webhooks for supported event types.Verify the signature
Every webhook includes a signature header. Compare it against an HMAC of the raw request body using your webhook secret:Respond quickly
Return a2xx response within 5 seconds. Queue heavy work (database writes, downstream API calls, emails) to a background job so bluSwap does not retry.
Handle retries idempotently
bluSwap retries failed deliveries with exponential backoff. Deduplicate using theevent_id:
1
Store processed event IDs
On receipt, check if the
event_id already exists in your database.2
Skip duplicates
If it exists, return
200 immediately without reprocessing.3
Persist before ack
Only acknowledge after your business logic and the event ID are committed to the database.
Test your endpoint with the sandbox environment before enabling production webhooks.
