Building

Webhooks

OBH can notify your server when a payment reaches a terminal state. The SDK does not verify these requests — you do, with your webhook signing secret. This page shows the exact algorithm.

The SDK does not handle webhooks

There is no webhook helper in @obhco/payments. Signatures must be verified by your server with the per-service webhook secret. The secret is separate from your API credential and is shown when created or rotated in OBH Admin.

What you receive

Webhooks are sent to the service’s configured webhook URL as POST requests with a JSON body. Two event types exist today:

Event	When
`payment.completed`	A payment was verified as completed.
`payment.failed`	A payment reached a failed terminal state.

Each delivery has a stable evt_... identifier and includes the OBH payment object.

Example payloadjson

1{2  "id": "evt_01J9Z6K3T4QW8M2",3  "type": "payment.completed",4  "createdAt": "2026-10-18T08:04:12.000Z",5  "data": {6    "id": "018f0000-0000-7000-8000-000000000001",7    "reference": "OBH-8B30F9C07A52D1E4",8    "externalOrderId": "IG-8821",9    "amount": "245000000.00",10    "currency": "IRR",11    "environment": "test",12    "status": "completed",13    "completedAt": "2026-10-18T08:04:10.000Z",14    "verifiedAt": "2026-10-18T08:04:10.000Z"15  }16}

Cancellation and expiry events

They are reserved for a later lifecycle implementation. Today, a cancelled or expired payment is discovered by retrieving it, not by a webhook.

Signature headers

http

1OBH-Event-Id: evt_01J9Z6K3T4QW8M22OBH-Timestamp: 17600000003OBH-Signature: t=1760000000,v1=<hex hmac>

The signature is an HMAC-SHA256 over <timestamp>.<raw request body>, keyed with your webhook signing secret and encoded as lowercase hex. The same timestamp appears both in OBH-Timestamp and in the t= component of OBH-Signature.

The API credential is not the webhook secret.
Signatures cover the exact bytes sent. Re-serialized JSON will not match.
The signing secret is encrypted at rest with a key derived from AUTH_SECRET. Rotating AUTH_SECRET without rotating service webhook secrets makes existing secrets unreadable.

Verify a signature

Read the raw body before parsing it. Then compare the computed digest with the v1 value using a timing-safe comparison, and reject timestamps outside a small tolerance window.

app/api/webhooks/obh/route.tsts

1import { createHmac, timingSafeEqual } from "node:crypto"2import { NextResponse } from "next/server"3 4import { obh } from "@/lib/obh"5 6const TOLERANCE_SECONDS = 3007 8export async function POST(request: Request) {9  // 1. Read the exact bytes that were signed.10  const rawBody = await request.text()11 12  const eventId = request.headers.get("obh-event-id")13  const timestamp = request.headers.get("obh-timestamp")14  const signature = request.headers.get("obh-signature")15 16  if (!eventId || !timestamp || !signature) {17    return new NextResponse("Missing signature headers", { status: 400 })18  }19 20  // 2. Reject stale deliveries (replay protection).21  const timestampSeconds = Number(timestamp)22  const age = Math.abs(Date.now() / 1000 - timestampSeconds)23 24  if (!Number.isFinite(timestampSeconds) || age > TOLERANCE_SECONDS) {25    return new NextResponse("Stale timestamp", { status: 400 })26  }27 28  // 3. Parse t=... and v1=... from the signature header.29  const parts = Object.fromEntries(30    signature.split(",").map((part) => {31      const [key, value] = part.split("=")32      return [key, value]33    })34  )35 36  const signatureTimestamp = parts.t37  const provided = parts.v138 39  if (!signatureTimestamp || !provided || signatureTimestamp !== timestamp) {40    return new NextResponse("Malformed signature", { status: 400 })41  }42 43  // 4. HMAC-SHA256 over `<timestamp>.<raw body>`.44  const expected = createHmac("sha256", process.env.OBH_WEBHOOK_SECRET!)45    .update(`${timestamp}.${rawBody}`)46    .digest("hex")47 48  const expectedBuffer = Buffer.from(expected, "utf8")49  const providedBuffer = Buffer.from(provided, "utf8")50 51  if (52    expectedBuffer.length !== providedBuffer.length ||53    !timingSafeEqual(expectedBuffer, providedBuffer)54  ) {55    return new NextResponse("Invalid signature", { status: 401 })56  }57 58  // 5. Verify first, parse second.59  const event = JSON.parse(rawBody) as {60    id: string61    type: "payment.completed" | "payment.failed"62    data: { reference: string }63  }64 65  if (!(await claimEventOnce(event.id))) {66    return NextResponse.json({ received: true, duplicate: true })67  }68 69  if (event.type === "payment.completed") {70    const payment = await obh.getPayment(event.data.reference)71 72    if (payment.status === "completed") {73      await markOrderPaidOnce(payment.externalOrderId!)74    }75  }76 77  return NextResponse.json({ received: true })78}

Do not verify a parsed-and-reserialized body

If your framework parses JSON and you stringify it again, whitespace and key order may change and the HMAC will not match. Capture the raw bytes first — request.text() in a Web Request, a raw-body parser in Express, or the raw body option in other frameworks.

Deduplicate events

Delivery is at-least-once. The same event id can arrive more than once, so record it and refuse to process it twice.

Idempotent processingts

1async function claimEventOnce(eventId: string) {2  try {3    await db.webhookEvent.create({ data: { id: eventId } })4    return true5  } catch (error) {6    // Unique constraint: already processed.7    return false8  }9}

Combine that with idempotent fulfilment (markOrderPaidOnce) so a duplicate delivery cannot ship two orders even if the event ledger is lost.

Delivery and retries

A 2xx response acknowledges delivery. Anything else, or a timeout, is retried with backoff.
Each delivery has a 5-second timeout and up to 6 attempts. The retry delays are 1 minute, 5 minutes, 30 minutes, 2 hours, and 6 hours.
The first attempt is made immediately after the terminal payment update.
A scheduled worker retries due deliveries. In this repository it runs with pnpm --filter web webhooks:process and is not yet scheduled automatically.
Each delivery row stores attempts, the next attempt time, and a sanitized error.

Production requires a scheduler

If the retry worker never runs, failed deliveries are never retried. A production deployment must schedule the worker (a cron job, a platform scheduler, or a queue) and monitor it.

Reacting correctly

Acknowledge quickly, then do durable work. The provider’s HTTP client waits for your response; expensive work should happen in a background job where possible.

Verify the signature and timestamp.
Deduplicate by event id.
Retrieve the payment for its authoritative state.
Perform idempotent fulfilment or failure handling.
Return 2xx.

Never fulfil based solely on the webhook body. It is a notification, not the state — and an old event can arrive after a newer one.

Operating the endpoint

Configure both a webhook URL and a signing secret in OBH Admin.
Store OBH_WEBHOOK_SECRET in server-side configuration. It is not the same value as OBH_SERVICE_KEY.
Rotate the secret in OBH Admin if it leaks. There is no recovery for a lost secret.
Log event ids and request ids, never the secret or the raw signature of a valid request.
Alert on repeated signature failures; they may indicate a misconfiguration or an attack.

See also Security and Next.js integration for a complete working route.