Outbound webhooks

Externa pushes domain events to a single HTTPS endpoint you configure in Project settings. Delivery is queued, signed with a project webhook secret (not an API key), and disabled when the URL is empty.

Configure

1. Admin → Settings → Project
2. Set Webhook URL (e.g. https://example.com/webhooks/externa or a temporary webhook.site URL)
3. Generate secret (or paste your own) and save — copy the secret into your receiver; Externa encrypts it at rest and never re-shows it in Inertia props
4. Optionally Send test event (type: ping) — requires a queue worker

Leave the URL empty to disable outbound events. Empty secret on save keeps the existing secret.

Envelope

{
  "id": "evt_01h…",
  "type": "item.updated",
  "created_at": "2026-07-24T12:00:00Z",
  "data": {
    "collection_id": 1,
    "collection_slug": "posts",
    "item_id": 42
  }
}

Bodies are minimal (ids / slug only). Full record dumps are out of scope for v1. Empty data is encoded as {} (object), not [].

Event types (v1)

Bulk import

CSV / remote JSON imports wrap row writes in OutboundWebhookDispatcher::withoutWebhooks() so a large import does not flood your endpoint.

Headers

Algorithm: HMAC-SHA256 over the exact raw JSON body bytes, using the project webhook secret. Prefix the hex digest with sha256=.

Timeouts: connect 3s, total 5s. Failed deliveries retry (3 tries, backoff 10s / 30s / 60s). Exhausted failures are logged; they do not break the admin/API write path.

Verify HMAC (on your receiver)

Sign the raw request body (not a re-encoded JSON object). Compare with a constant-time equality check.

Node

import crypto from 'node:crypto'

function verify(rawBody, secret, signatureHeader) {
  const expected =
    'sha256=' +
    crypto.createHmac('sha256', secret).update(rawBody).digest('hex')
  const a = Buffer.from(expected)
  const b = Buffer.from(signatureHeader || '')
  return a.length === b.length && crypto.timingSafeEqual(a, b)
}

PHP

$expected = 'sha256='.hash_hmac('sha256', $rawBody, $secret);
hash_equals($expected, $signatureHeader);

Try / test

End-to-end (recommended)

1. Open webhook.site (or run a local receiver) and copy its unique URL
2. Admin → Settings → Project → paste as Webhook URL, generate/save secret, keep a copy of the secret
3. Start a queue worker
4. Click Send test event, or create/update an item in the admin
5. Inspect the POST on webhook.site: JSON envelope + X-Externa-* headers
6. Point the URL at your real receiver and verify HMAC with the snippets above

Practice signing with Bruno (optional)

The externa-bruno collection includes PublicApi/Webhooks/Verify Webhook Signature.

Use it to:

• See the envelope shape and header names Externa sends
• Compute sha256=<hmac> locally (same secret as Project settings → webhook_secret / EXTERNA_WEBHOOK_SECRET in Bruno .env)
• Set X-Externa-Signature on the request and POST to your receiver to exercise verification code

Bruno is acting as a client toward your webhook endpoint, not as a caller of Externa’s Public API.

Full Bruno notes: externa-bruno README — Webhooks helper.

vs inbound API keys

Do not reuse an API key as the webhook signing secret.