Webhooks
SenteRail sends signed webhooks so your system can react to payment and workflow updates. Your receiver should verify the signature before changing order, member, accounting, or fulfilment state.
Customer Webhook Responsibilities
| Responsibility | What to do |
|---|---|
| Authenticity | Verify the SenteRail signature and timestamp before processing |
| Idempotency | Store event IDs and ignore duplicate deliveries |
| Ordering | Treat events as asynchronous and reconcile when order is uncertain |
| Availability | Return a success response only after durable persistence |
| Recovery | Keep a manual or automated reconciliation path for missed updates |
Signature Verification
Outbound webhook headers use X-SenteRail-*, including X-SenteRail-Signature. Verify the signature with the webhook signing secret assigned to your account. Reject stale timestamps and malformed signatures.
ts
const signedPayload = `${timestamp}.${rawBody}`
const expectedSignature = hmacSha256(signingSecret, signedPayload)Use constant-time comparison when checking the received signature.
Retry And Dedupe
SenteRail may retry delivery when your endpoint is unavailable or returns an error. Your webhook handler should be safe to run more than once for the same event.
Store:
- event ID
- event type
- payment or workflow reference
- received timestamp
- processing result
Reconciliation Fallback
Webhooks are not a replacement for reconciliation. Network issues, provider timing, and operational incidents can create delayed or out-of-order updates. Use Reconciliation to compare SenteRail events with your own records.
Provider Callbacks
Some payment providers also send callbacks to SenteRail. Those provider-facing callbacks are not your integration endpoint. Your integration should listen for SenteRail's outbound signed events and use reconciliation when a provider event is delayed or uncertain.