Receiving webhooks - Batch Relay API

Your endpoint must accept an HTTPS POST whose raw body is one CloudEvents 1.0 structured JSON document. Return a 2xx only after the event is durably safe to acknowledge.

Verify before parsing

Batch Relay uses the Standard Webhooks headers:

webhook-id: msg_...
webhook-timestamp: 1723833751
webhook-signature: v1,...

These three required headers are also declared on the AsyncAPI HTTP operation through the reusable standardWebhookHeaders component. Verify the signature over the exact raw request bytes before JSON parsing or normalization. Do not reconstruct JSON, stringify a parsed object, or substitute the CloudEvent id for the Standard Webhooks delivery ID.

import { Webhook } from "standardwebhooks";

export async function POST(request: Request) {
  const rawBody = await request.text();
  const verifier = new Webhook(process.env.BATCH_RELAY_WEBHOOK_SECRET!);

  let event: Record<string, unknown>;
  try {
    event = verifier.verify(rawBody, {
      "webhook-id": request.headers.get("webhook-id") ?? "",
      "webhook-timestamp": request.headers.get("webhook-timestamp") ?? "",
      "webhook-signature": request.headers.get("webhook-signature") ?? ""
    }) as Record<string, unknown>;
  } catch {
    return new Response("invalid signature", { status: 400 });
  }

  // Validate event.specversion and event.type before handling the payload.
  // Persist the CloudEvent id transactionally before returning success.
  return new Response(null, { status: 204 });
}

Use the current Standard Webhooks library for your language. Store the webhook secret outside source control and rotate it in the Developer Dashboard when needed.

Dedupe and ordering

Deduplicate by the CloudEvent envelope id, not by webhook-id. webhook-id identifies a delivery attempt; id identifies the immutable business event. Keep a durable record of successfully processed CloudEvent IDs. If an event has already been processed, safely return a 2xx without repeating its side effect. For stateful resources, compare resourceversion with the latest version your integration has applied. Messages can be delayed, retried, or delivered out of order. A lower resource version must not overwrite newer local state.

Retry-safe processing

Read the exact raw body.
Verify Standard Webhooks headers.
Validate the CloudEvents envelope and topic schema.
Start a database transaction.
Record the CloudEvent ID and apply the side effect exactly once.
Commit, then return a 2xx.

If any step cannot complete durably, return a non-2xx response so delivery can be retried. Do not return success merely because background work was queued without a durable handoff.

Capability and destination boundaries

Only configured destinations receive topics available to their Batch Relay account. Public topic definitions can be read here; account-specific topic availability and destination configuration stay in the authenticated Developer Dashboard. An unavailable capability results in no delivery, not a redacted payload with a different shape.

​Verify before parsing

​Dedupe and ordering

​Retry-safe processing

​Capability and destination boundaries

Verify before parsing

Dedupe and ordering

Retry-safe processing

Capability and destination boundaries