1. Create an endpoint
Use an API key with webhooks.write. Partner- and merchant-scoped keys must
select an authorized branch according to your account hierarchy.
Save the returned endpoint id.
The create response does not include a signing secret. Retrieve it through the
dedicated endpoint in the next step.
2. Retrieve the signing secret
Store the returned whsec_ value in a secret manager. It is separate from the
API key and must never be exposed in browser code or logs.
3. Receive and verify
Modulus sends a JSON POST with Webhook-Id, Webhook-Timestamp, and
Webhook-Signature. Verify the signature against the exact raw request bytes
before parsing JSON. See Verify signatures.
4. Acknowledge safely
Persist and deduplicate the event by its envelope id, return a 2xx response
quickly, and process fulfillment asynchronously. Non-2xx responses and
timeouts are retried automatically.
Never use your Modulus API key to verify a webhook. Every endpoint has its own
endpoint signing secret.
