# Customer webhooks

Outgoing event delivery for your workspace. Register an HTTPS endpoint, verify
the one-time signing secret, and receive signed events with bounded retries.

## Register an endpoint

```bash
curl -s -X POST -H "Authorization: Bearer $PUBLISHER_KEY" \
  -H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/json" \
  $BASE/webhooks -d '{"url": "https://example.com/hooks/autoposted"}'
```

- The signing secret (`whsec_…`) is returned **once**: in the first successful
  creation response. Store it; an idempotent replay of the same creation returns
  the endpoint without the secret, and it cannot be shown again.
- Destinations must be **HTTPS**, publicly resolvable, and free of embedded
  credentials. Requests to private, loopback, link-local (including cloud
  metadata), unique-local and multicast addresses are refused before any
  connection is made, and redirects are never followed.
- Registration enqueues a **targeted** `webhook.verification` event for that
  endpoint, independent of its `eventTypes` filter. Ordinary events flow only
  after your endpoint answers the verification with 2xx.

## Verifying deliveries

Every request carries:

| Header | Meaning |
|---|---|
| `x-publisher-event-id` | Stable event ID: identical across retries and replays |
| `x-publisher-event-type` | Event type, e.g. `post.published` |
| `x-publisher-timestamp` | Unix seconds |
| `x-publisher-signature` | `t=<ts>,v1=<hex>` |

The signature is HMAC-SHA256 over `${t}.${event_id}.${raw_body}` using your
signing secret. Verify with a ±300 second tolerance and reject replays outside
it. Node example:

```js
import { createHmac, timingSafeEqual } from 'node:crypto';

function verify(secret, headers, rawBody) {
  const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(headers['x-publisher-signature']);
  if (!m) return false;
  const [t, v1] = [Number(m[1]), m[2]];
  if (Math.abs(Date.now() / 1000 - t) > 300) return false;
  const expected = createHmac('sha256', secret)
    .update(`${t}.${headers['x-publisher-event-id']}.${rawBody}`)
    .digest('hex');
  return timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}
```

Always verify against the **raw** request body before parsing.

## Event envelope

```json
{
  "id": "0192d0d0-0000-7000-8000-00000000000f",
  "type": "post.published",
  "createdAt": "2026-11-09T12:00:01Z",
  "apiVersion": "2026-11-09",
  "data": { "postId": "…", "deliveryId": "…", "accountId": "…" }
}
```

Initial event catalog (extensible; `eventTypes` filters at registration):

- `webhook.verification`: challenge payload; answer 2xx to activate the endpoint
- `post.published`: one destination confirmed with a native receipt
- `delivery.failed`: one destination failed terminally
- `delivery.requires_action`: consent/reconnection/late-review required

Aggregate post outcomes (`post.partially_published`, `post.failed`) are not
emitted yet; they are documented here only once a producer exists, so don't
rely on them. Subscribe to the per-destination events above and derive batch
state from the post's delivery outcomes.

## Retries, replay and disabling

- Attempts: immediately, then +1m, +5m, +30m, +2h, +8h. Retries reuse the **same
  event ID and byte-identical body** so you can deduplicate safely.
- 2xx = delivered. 429/5xx/timeouts retry. Other 4xx fail permanently for that
  event (fix the endpoint, then replay).
- **410 Gone** disables the endpoint: no further events are enqueued to it.
- Operator-authorized replay through the internal webhook service re-sends an event with its
  original ID. An actively-leased in-flight attempt is never yanked; replay
  reports that the event is busy and can be retried shortly.

## Operational notes

- Delivery diagnostics store only safe outcome codes: never your secret,
  signatures, request headers or response bodies. Payloads are additionally
  sanitized: provider/OAuth secrets and media presign URLs are stripped before
  anything is queued.
- Endpoints are workspace-scoped: possession of an endpoint UUID from another
  workspace does nothing.
- Delivery is at-least-once per accepted event occurrence; deduplicate on
  `x-publisher-event-id`.

## Developer tools availability

The Developers page lists workspace API keys and webhook endpoints independently
of signing-secret encryption configuration. Creating a webhook requires valid
server encryption configuration; ask the deployment operator to resolve a
configuration warning. API-key management remains available. Existing signing
secrets are never shown again.
