Webhooks
Webhooks let your server react to payments as they happen — instead of polling GET /api/v1/payment for status changes, Stitch Express pushes a small JSON payload to a URL you control as soon as a customer completes payment. They are the recommended way to learn that a payment completed.
Webhooks cover successful payments only. Non-success outcomes are not delivered; read those from the originating resource — GET /api/v1/payment-links/{id} for an expired or cancelled link, GET /api/v1/terminal-sessions/{id} for a failed terminal session.
Webhooks are delivered via Svix. Svix handles retries, replay protection, and signature verification — you only need to register an endpoint and verify the signature on each delivery.
Step 1: Register an Endpoint
Send your URL to POST /api/v1/webhook. The response includes a signing secret that you'll use to verify deliveries — store it securely (e.g. in your secret manager) the moment you receive it. The API does not let you re-fetch it later.
curl -X POST 'https://express.stitch.money/api/v1/webhook' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"url": "https://yoursite.com/webhooks/stitch"
}'
Response:
{
"success": true,
"data": {
"secret": "whsec_1234567890abcdef1234567890abcdef"
}
}
Requirements:
- The URL must be publicly reachable over HTTPS.
- You can register multiple endpoints — each gets its own signing secret.
- Re-registering the same URL returns a
409 Endpoint already exists. Delete and rotate from the Webhooks page in the dashboard.
Step 2: Event Types
| Event | When it fires |
|---|---|
payment.paid | The customer has successfully completed payment |
This is the only event type. There is no event for failures, cancellations or expiry.
Webhook Payload
{
"amount": 5000,
"id": "payment-uuid",
"status": "PAID",
"type": "LINK",
"linkId": "link-uuid",
"consentId": null,
"subscriptionId": null,
"terminalSessionId": null
}
| Field | Description |
|---|---|
amount | Payment amount in South African cents (e.g. 5000 = R50.00) |
id | The payment ID — pass to GET /api/v1/payment/{id} for full details |
status | PAID |
type | How the payment was created: LINK, CONSENT, SUBSCRIPTION, or TERMINAL |
linkId | Set when type=LINK — the originating payment link |
consentId | Set when type=CONSENT — the originating card consent |
subscriptionId | Set when type=SUBSCRIPTION — the originating subscription |
terminalSessionId | Set when type=TERMINAL — the terminal session id returned by POST /api/v1/terminal-sessions |
Exactly one of linkId, consentId, subscriptionId, or terminalSessionId is non-null per payload — match on type to pick the right one.
Terminal Sessions
For card-present payments, payment.paid fires when the terminal session reaches SUCCESS. Match it to your session using terminalSessionId, which is the id you received from POST /api/v1/terminal-sessions.
FAILURE is never delivered by webhook — a declined card, a cancellation on the terminal, an expired session, or a cancelled_by_api session produce no event. Poll GET /api/v1/terminal-sessions/{id} for the in-store outcome (the cashier is usually waiting on it), and treat payment.paid as the durable server-side confirmation.
There is no API call to end a session; the terminal stays live until the customer pays, cancels on the device, or the session expires. If the cashier abandons a sale and you later receive payment.paid for that terminalSessionId, the customer was charged — refund it with POST /api/v1/payment/{id}/refund.
Verifying Webhook Signatures
Every webhook request must be verified before you trust it. Anyone who guesses your URL can POST to it; the signature is what proves it came from Stitch.
Svix sends three headers:
svix-id— Unique message IDsvix-timestamp— Unix timestamp of the deliverysvix-signature— HMAC signature(s) of{svix-id}.{svix-timestamp}.{body}
Use the signing secret from Step 1 with one of the Svix libraries — they handle the HMAC math, timestamp tolerance, and signature rotation for you.
Node.js example:
import express from 'express';
import { Webhook } from 'svix';
const wh = new Webhook(process.env.STITCH_WEBHOOK_SECRET);
// Mount the raw-body parser ONLY on the webhook route, before any
// global express.json() / bodyParser middleware. With express.raw,
// req.body is a Buffer of the original request bytes.
app.post('/webhooks/stitch', express.raw({ type: 'application/json' }), (req, res) => {
try {
const payload = wh.verify(req.body, {
'svix-id': req.headers['svix-id'],
'svix-timestamp': req.headers['svix-timestamp'],
'svix-signature': req.headers['svix-signature'],
});
// payload is the verified, parsed JSON body
handlePaymentEvent(payload);
res.status(200).end();
} catch (err) {
res.status(400).send('Invalid signature');
}
});
You must verify against the raw request body — JSON re-serialization changes whitespace and breaks the HMAC. If you use express.json() or bodyParser.json() globally, make sure it does not run before this route (mount the raw parser first, or scope the JSON parser to other routes).
Retries
Svix retries failed deliveries with exponential backoff over ~24 hours. A delivery is considered successful only if your endpoint returns a 2xx status code.
Make your handler idempotent. A retry can deliver the same svix-id you already processed — keep a short-lived record of seen IDs (e.g. in Redis) and skip duplicates.
Common Issues
| Symptom | Cause |
|---|---|
409 Endpoint already exists | The URL is already registered. Delete from the dashboard before re-registering. |
| Signature verification fails | You're verifying against parsed/re-serialized JSON instead of the raw body. |
| Events delivered repeatedly | Your handler isn't returning 2xx — Svix treats anything else as failure. |
| No events arriving | URL not publicly reachable, or you haven't taken any test/live payments yet. |