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

EventWhen it fires
payment.paidThe 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
}
FieldDescription
amountPayment amount in South African cents (e.g. 5000 = R50.00)
idThe payment ID — pass to GET /api/v1/payment/{id} for full details
statusPAID
typeHow the payment was created: LINK, CONSENT, SUBSCRIPTION, or TERMINAL
linkIdSet when type=LINK — the originating payment link
consentIdSet when type=CONSENT — the originating card consent
subscriptionIdSet when type=SUBSCRIPTION — the originating subscription
terminalSessionIdSet 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 ID
  • svix-timestamp — Unix timestamp of the delivery
  • svix-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

SymptomCause
409 Endpoint already existsThe URL is already registered. Delete from the dashboard before re-registering.
Signature verification failsYou're verifying against parsed/re-serialized JSON instead of the raw body.
Events delivered repeatedlyYour handler isn't returning 2xx — Svix treats anything else as failure.
No events arrivingURL not publicly reachable, or you haven't taken any test/live payments yet.