Skip to main content
We notify you if the purchase needs something.
  1. 1ReceiveSapiom sends an event to your receiver.
  2. 2VerifyCheck the signature on the request.
  3. 3Store and respondSave the event, then reply within 10 seconds.
  4. 4Read the transactionFollow its next action.
Create one webhook (HTTPS receiver) for your platform. This covers all of your users and checkout types.

Register your receiver

Use an API key from Create key in the dashboard’s API keys; it has the org.write permission this needs. A platform key from Create platform key doesn’t. Store signingSecret server-side only.

Verify the signature

Sapiom signs each request with the Standard Webhooks headers. Verify them with your signing secret:
verify-webhook.ts

Events

Sapiom sends three events:
  • transaction.action_required (action: human_approval or security_code)
  • transaction.payment_ready
  • transaction.closed (status denied or cancelled, reason)
Each event names its transaction. Read the purchase after each one:

Retries and duplicates

Sapiom retries after about a minute, backing off to six hours. A retry has the same event id, so ignore ids you’ve already seen.

Read, replace or remove the receiver

Replacing the URL keeps the signing secret. To read the receiver:
To replace it, send the same PUT as above with the new URL. To remove it: