Webhooks

Webhook delivery is optional and belongs to your organization. In Dashboard → Webhooks, add one HTTPS endpoint and copy the signing secret shown once. Every application in the organization then uses that event stream. Events created before the endpoint's first activation are not delivered automatically.

import { verifyDomain0Webhook } from 'domain0/contracts'

export async function POST(request: Request) {
  const event = await verifyDomain0Webhook({
    body: new Uint8Array(await request.arrayBuffer()),
    headers: request.headers,
    secretKeyring: {
      [process.env.DOMAIN0_WEBHOOK_KEY_ID!]: decodeBase64(
        process.env.DOMAIN0_WEBHOOK_SECRET!,
      ),
    },
  })

  await processOnceInTransaction(event.eventId, () => applyEvent(event))
  return new Response(null, { status: 204 })
}

Verify the untouched request bytes before parsing them. Store the event ID and your business mutation in one database transaction. Return success when that event ID was already processed.

Envelope

Schema v1 includes:

• eventId
• type
• connectionId
• applicationId
• tenantId
• sequence
• occurredAt
• typed attributes

The signed delivery also includes an x-domain0-timestamp header for replay protection. That transport timestamp is separate from the event's occurredAt field.

Use the exported discriminated union for exhaustive event handling. Do not trust duplicated identity or event headers until signature verification passes.

Operations

The Webhooks dashboard shows each delivery attempt, HTTP status, latency, and safe failure reason. Domain0 retries transport errors, HTTP 408, HTTP 429, and 5xx responses with bounded backoff. A failed event becomes replayable after its retry budget is exhausted.

Use Send test event after setup. Test deliveries use the same schema, signature, and network path as production events and include attributes.test = "true".

Rotating the signing secret changes the key ID immediately. Add the new key and secret to your receiver before removing the old receiver key. Pausing delivery keeps new events durable until the endpoint is enabled again.