Skip to main content
Raast workflows are asynchronous. Customers can approve or reject requests in their banking apps, and payment, payout, refund, and settlement states can change after the originating API request returns. Safepay sends those changes to your backend through webhooks.

​
How webhooks work

1

Register an endpoint

Create an endpoint with POST /v1/aggregators/{{aggregator_id}}/webhooks. Subscribe to exact events or category filters such as payment.*.
2

Receive a signed event

Safepay sends an HTTP POST containing the event JSON and five X-SFPY-* delivery headers.
3

Verify and persist

Verify the timestamp and HMAC signature over the raw body, then persist the event idempotently using X-SFPY-EVENT-ID.
4

Acknowledge and process

Return a 2xx promptly, then apply business logic asynchronously. Poll the corresponding API when reconciliation is necessary.

​
Delivery headers

The signature is calculated over X-SFPY-TIMESTAMP + '.' + raw_body using the decoded webhook secret. See Webhooks delivery for the complete verification algorithm, retry rules, and rotation procedure.

​
Event payloads

Every event uses a versioned envelope containing:
  • event metadata such as identifier, timestamp, kind, code, and version;
  • aggregator_id and, when applicable, partner_id;
  • the public webhook_event_type; and
  • a resource snapshot under subject.payment.
See Webhook events and payloads for a field reference and complete JSON examples.

​
Event families

Payouts are payment resources with subject.payment.type equal to PAYOUT or SETTLEMENT_PAYOUT; subscribe to payment.* for payout state changes. There is no payout.* event family.

​
Reliability model

Webhook delivery is at least once and ordering is not guaranteed. Handle duplicate events and delayed earlier states safely. Safepay retries transport errors and 5xx responses five times after the initial request. Any 2xx acknowledges the delivery; terminal 4xx responses are not retried.
Store the event before acknowledging it, enforce a unique constraint on the event ID, and compare the current resource state before applying a transition.

​
Secrets and rotation

The create and rotate responses return a base64-encoded signing secret. Treat every secret value returned by webhook-management APIs as sensitive. Decode it before computing HMAC-SHA256. Rotation replaces the stored secret immediately; Safepay does not keep both secrets active. Because a request already in flight can still be signed with the old secret, retain the previous secret briefly as an aggregator-side verification fallback. See Rotate the signing secret.

​
Manage endpoints and inspect deliveries

The delivery API surfaces WD_PENDING, WD_DELIVERED, WD_FAILED, and WD_DEAD (WD_FAILED is reserved and not currently assigned; deliveries stay WD_PENDING through retries). There is no public manual-redelivery endpoint; reconcile a dead delivery through the corresponding resource API.

​
See also