Skip to main content
bluSwap posts webhook events to your configured callback URL when transaction states change. This guide covers configuration, signature verification, and idempotent handling.

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 a 2xx 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 the event_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.