Webhooks
Accept an event quickly, prove it is authentic, and process it once.
Verify the raw delivery, reject stale events, acknowledge quickly, and process each event once.
Implementation checklist
Read raw bytes
Do not parse or transform the body before signature verification.
Check time and signature
Reject stale timestamps and signatures that do not match the supplied secret.
Acknowledge quickly
Return the documented success response before starting long-running work.
Deduplicate
Use the event ID as the durable once-only processing boundary.
Request and result
Saleringo-Event-Id: evt_...
Saleringo-Delivery-Timestamp: 2026-08-18T00:00:00Z
Saleringo-Delivery-Signature: v1=...verify(rawBody, timestamp, signature)
storeOnce(eventId)
enqueue(parsedEvent)
return acceptedResponse()Failure handling
| Status | Meaning | Client action |
|---|---|---|
| 401 | Credential is missing, expired, or invalid | Stop; refresh through the approved server flow. |
| 403 | Identity lacks the exact permission or scope | Do not retry; request an access review. |
| 409 | State, version, idempotency, or approval conflicts | Read the conflict and reconcile before another command. |
| 422 | The request does not match the published schema | Correct the named fields; do not retry unchanged. |
| 429 | The integration is sending too quickly | Honor the supplied wait guidance and apply backoff. |
| 5xx | A temporary service failure may have occurred | Preserve IDs; retry only when the operation permits it. |
Implementation support
Do not send credentials, customer secrets, or raw payment data. Include the contract version, environment, operation, timestamp, and non-sensitive correlation ID.