Developer Webhooks

Developer webhooks tell your server when a payment created through the Seev API reaches a final status, so you can fulfil an order or update your records without polling. They require developer access and a webhook endpoint configured for the environment you are working in. Creating keys is covered in API Keys.

SeevPlus sends these events itself. It first consumes and processes the underlying gateway event, then emits a stable merchant-facing event to your endpoint. A browser redirect back to your site is a user-experience signal and never proof of payment, so fulfil against a verified webhook or a server-side verification call.

Create an endpoint

Open Seev API -> Webhooks and create an endpoint for the environment you want. Sandbox and production endpoints are configured separately and never receive each other's events.

The response returns the endpoint plus its signing secret, which is the only time the secret is shown:

{
    "id": "68c1f4a1c3b5d2a91f0e7742",
    "url": "https://api.example.com/webhooks/seev",
    "events": ["payment.failed", "payment.succeeded"],
    "env": "production",
    "status": "active",
    "signingSecret": "3Qk9vT2mYb1sJ7pR0aZ4xLd8HcN6fUeW2gK5nB1oQ3s"
}

The signing secret is 32 random bytes in base64url form with no prefix. Store it in the same secrets manager that holds your API keys. It is unique to this endpoint, it never belongs in browser or mobile code, and it is the only thing that distinguishes a genuine Seev request from a forged one.

Your endpoint must be reachable from the public internet. For local development, expose it through a tunnel such as ngrok or Cloudflare Tunnel and register the tunnel URL.

Subscribe to the right events

A transaction sitting at pending emits nothing. There is no payment.pending event, so a customer who abandons checkout produces no delivery at all, and your reconciliation has to notice the silence rather than wait for a message.

Subscribe to both events unless you genuinely handle only one. The failure handler is what keeps an order unpaid and offers the customer a retry instead of leaving it stuck.

Read the payload

Every delivery is a POST with a JSON body in this envelope:

{
    "id": "68c1f52ac3b5d2a91f0e7751",
    "event": "payment.succeeded",
    "env": "production",
    "createdAt": "2026-07-18T21:09:12Z",
    "data": {
        "transaction": {
            "id": "68c1f4d9c3b5d2a91f0e7748",
            "env": "production",
            "product": "checkout",
            "type": "payment",
            "amount": 100,
            "currency": "GHS",
            "status": "completed",
            "reference": "PAY-20260718-f23159df-9df8-4e69-8306-c11d71ead351",
            "gatewaySessionRef": "PAY-20260718-f23159df-9df8-4e69-8306-c11d71ead351",
            "checkoutUrl": "https://pay.seevplus.com/PAY-20260718-f23159df-9df8-4e69-8306-c11d71ead351",
            "createdAt": "2026-07-18T21:08:46Z",
            "updatedAt": "2026-07-18T21:09:12Z"
        }
    }
}

Verify the signature

Every request carries four headers:

The signature covers the timestamp and the exact bytes of the body:

"v1=" + hex(HMAC_SHA256(signingSecret, timestamp + "." + rawBody))

Verify against the raw body before you parse it. Re-serializing the JSON changes the bytes and the digest will not match.

import crypto from 'crypto';

export function verifySeevWebhook({
    rawBody,
    timestamp,
    signature,
    secret,
}: {
    rawBody: string;
    timestamp: string;
    signature: string;
    secret: string;
}) {
    const age = Math.abs(Date.now() / 1000 - Number(timestamp));
    if (!timestamp || Number.isNaN(Number(timestamp)) || age > 300) {
        return false;
    }

    const expected =
        'v1=' +
        crypto
            .createHmac('sha256', secret)
            .update(`${timestamp}.${rawBody}`)
            .digest('hex');

    const expectedBuf = Buffer.from(expected);
    const actualBuf = Buffer.from(signature || '');
    if (expectedBuf.length !== actualBuf.length) {
        return false;
    }
    return crypto.timingSafeEqual(expectedBuf, actualBuf);
}

timingSafeEqual throws when the two buffers differ in length, which is exactly what a garbage or missing signature header produces, so compare lengths first and return false rather than letting the exception become a 500. A 500 is recorded as a failed delivery and gives an attacker a way to tell malformed signatures apart from wrong ones.

The 300-second window above is your choice, not a Seev-enforced limit. Seev signs with the timestamp at send time and does not reject anything on age; rejecting old timestamps is what stops a captured request being replayed at you later. Keep the window wide enough to survive clock skew on your own host.

When verification fails

Return 401 for a request you cannot verify, and do not apply any side effect. That failure appears in the webhook logs with HTTP status 401, which is what you want when you are diagnosing a secret mismatch.

Handle retries, duplicates, and ordering

This is the part most integrations get wrong, so the behaviour is worth stating exactly.

One automatic attempt. SeevPlus sends each event once. There is no automatic retry schedule and no backoff. The delivery is given 8 seconds; if your endpoint has not responded by then, the attempt is cancelled and recorded as failed with the error text from the timeout. Any 2xx marks the delivery delivered; anything else, along with connection failures, marks it failed.

Retries are manual and change the event ID. You can replay any delivery from the dashboard, including one that already succeeded. A replay writes a new event log with the same payload body but a fresh event ID, in both X-Seev-Event-ID and the payload's id, linked back to the original through retriedFromEventId. Deduplicating on the event ID therefore does not protect you from a manual replay. Deduplicate on data.transaction.reference together with the status you applied.

Duplicates arrive from three directions. A manual replay is one. A second is having several endpoints subscribed to the same event in the same environment, each of which receives its own delivery. A third is a transaction that changes status more than once, which emits a separate event per transition.

Ordering is not guaranteed. Deliveries are dispatched concurrently, one goroutine per subscribed endpoint, and nothing serializes them or waits for the previous attempt. Two events for the same transaction can arrive out of order or overlap. Treat data.transaction.status as the authority for the state at the moment of the event, use updatedAt to discard an event older than what you have already applied, and never derive state from arrival order.

Events fire on transition, not on inspection. SeevPlus emits an event only when a transaction's stored status actually changes, so calling the verify endpoint repeatedly against an unchanged transaction produces nothing. The flip side is that your own verify call is one of the things that can discover a status change, which means a GET from your server can be what triggers the webhook you then receive.

A handler that survives all of the above:

export async function POST(req: Request) {
    const rawBody = await req.text();

    const valid = verifySeevWebhook({
        rawBody,
        timestamp: req.headers.get('X-Seev-Timestamp') || '',
        signature: req.headers.get('X-Seev-Signature') || '',
        secret: process.env.SEEV_WEBHOOK_SECRET!,
    });

    if (!valid) {
        return new Response('Invalid signature', { status: 401 });
    }

    const event = JSON.parse(rawBody);
    const tx = event.data?.transaction;

    // Deduplicate on the payment reference, which survives manual replays,
    // and ignore an event older than the state already recorded.
    const applied = await recordEventIfNewer({
        reference: tx.reference,
        status: tx.status,
        updatedAt: tx.updatedAt,
    });

    if (applied) {
        await enqueueFulfilment(tx.reference); // slow work happens off the request
    }

    return Response.json({ received: true });
}

Inspect a delivery

Webhook logs records every attempt, successful or not.

The stored response body is truncated at 4096 bytes, so a long error page from your server is cut off in the log. Read these together with the corresponding row in Developer Transactions when a payment and your records disagree.

Related docs

• Developer API Keys
• Developer Transactions
• Checkout API
• Idempotency