Receive and process webhooks

Who this is for

Developers implementing a production webhook receiver, beyond the basic signature check covered in verify webhook signatures.

Before you begin

• A working signature-verification function.
• A database table (or equivalent) to record processed delivery IDs and order-fulfilment state.

Steps

1. Capture the raw request body.
2. Validate the timestamp window.
3. Compute v1=HMAC_SHA256(secret, timestamp + "." + rawBody).
4. Compare signatures with a timing-safe function.
5. Reject a delivery whose ID has already been processed.
6. Parse the JSON body and confirm event === "checkout.paid".
7. Look up your order using the stored checkout reference.
8. Commit a unique fulfilment transition, then return a 2xx response.

// Pseudocode for the database boundary.
await db.transaction(async (tx) => {
  const inserted = await tx.insertProcessedWebhookIfAbsent(deliveryId);
  if (!inserted) return;
  await tx.markOrderPaidOnce({ orderId, checkoutRef, txHash });
});

Expected result

Return a 2xx status only after the event is durably recorded. If your endpoint returns a failure, Outpay retries according to its own retry schedule.

Common problems

Related documentation

• Verify webhook signatures — the signature check this guide builds on.
• Events — the exact payload shape referenced above.
• Idempotency — the equivalent pattern for checkout creation.