What are webhooks?
Webhooks let Rolla notify your server in real time whenever one of your deposits or payouts changes status — so you no longer need to poll the transaction endpoints. When an event occurs, Rolla sends an HTTPPOST request to a URL you configure, with a JSON payload describing the transaction.
Webhooks cover all supported transaction types and corridors:
- Fiat deposits and payouts (e.g. NGN, USD, XAF)
- Stablecoin deposits and payouts (USDC) on Solana
Webhooks are available to businesses using the Rolla external API. Events are sent for your deposits and payouts only.
Setting up an endpoint
Configure webhook endpoints from your Rolla Dashboard under API → Webhooks. For each endpoint you provide:| Field | Description |
|---|---|
| URL | An https:// endpoint on your server that will receive events |
| Events | Which events to subscribe to (see Events) |
| Sign requests | Optional. When enabled, a signing secret is generated so you can verify signatures. Leave it off and requests are sent unsigned, with no secret |
A signing secret only exists when Sign requests is enabled. If you create an endpoint with signing off and later turn it on, a secret is generated at that point. While signing is enabled, the secret can be viewed any time from the dashboard (API → Webhooks → ⋯ → Reveal secret), so you don’t need to store it elsewhere. If you suspect it’s compromised, rotate it with Regenerate secret — the old secret stops working immediately.
How delivery works
Rolla builds and signs the event
A JSON payload is assembled with the full transaction details and (optionally) signed with your endpoint’s secret.
Rolla POSTs to your URL
Your server receives the event. Respond with a
2xx status code as quickly as possible to acknowledge receipt.Failed deliveries are retried
If your endpoint is unreachable or returns a
5xx/429, Rolla retries with backoff.Responding to webhooks
Your endpoint should return a2xx HTTP status code to acknowledge receipt. Anything else is treated as a failed delivery.
Request headers
Every webhook request includes these headers:| Header | Description |
|---|---|
X-Rolla-Event | The event type, e.g. transaction.completed |
X-Rolla-Event-Id | Stable id for this logical event — use it to deduplicate |
X-Rolla-Delivery | Unique id for this specific delivery attempt |
X-Rolla-Signature | HMAC signature for verification (only when signing is enabled) |
User-Agent | Rolla-Webhooks/1.0 |
Next steps
Events
The event types and transaction lifecycle.
Payloads
The payload schema and sample events.
Signature Verification
Verify that events genuinely came from Rolla.
Delivery & Retries
Retry behavior, logs, and replay.