Merge pull request #868 from hookdeck/chore/docs-webhook-event-id-headers

chore(docs): clarify webhook event-id header and idempotency

Author: leggetter

docs/apis/openapi.yaml

@@ -1790,7 +1790,7 @@ components:
       properties:
         id:
           type: string
-          description: Optional. A unique identifier for the event. If not provided, a UUID will be generated.
+          description: Optional. A unique identifier for the event. If not provided, a UUID will be generated. A stable id enables publish idempotency (see `duplicate` in the response) and is the value receivers should use to deduplicate webhook deliveries — by default sent as the `X-Outpost-Event-Id` header (prefix configurable).
           example: "evt_custom_123"
         tenant_id:
           type: string

docs/content/destinations/webhook.mdoc

@@ -59,17 +59,25 @@ Outpost sends an HTTP POST request:
 ```
 POST /webhooks HTTP/1.1
 Content-Type: application/json
-x-outpost-id: evt_abc123
+x-outpost-event-id: evt_abc123
 x-outpost-topic: user.created
-x-outpost-timestamp: 1704067200
-x-outpost-signature: t=1704067200,v0=abc123...
+x-outpost-timestamp: 2024-06-01T08:23:36Z
+x-outpost-signature: v0=abc123def456...
 x-outpost-source: signup-service
 
 {"user_id": "usr_123", "email": "user@example.com"}
 ```
 
 The request body contains the event's `data` field as JSON. The `metadata` field is translated to headers using the configured prefix.
 
+### Event ID header and idempotency
+
+Webhook delivery is **at-least-once** (see [Event delivery & retries](/docs/outpost/features/event-delivery)). Your handler should deduplicate using the **event id** — the same stable `id` you set when [publishing](/docs/outpost/publishing/events) (Outpost may redeliver on retries).
+
+In **default** mode, that id is sent as the system **`event-id`** metadata field. The HTTP header name is **`{header_prefix}{metadata-key}`** with **no extra separator** — the prefix and key are concatenated as-is. So the default prefix `x-outpost-` plus `event-id` yields **`X-Outpost-Event-Id`**; a prefix without a trailing separator (for example `x-acme`) would produce `x-acme` + `event-id` → **`X-Acmeevent-Id`** (Go canonicalizes the wire name). Include a trailing hyphen in the prefix when you want a conventional shape like **`X-Acme-Event-Id`**. Change the prefix with **`DESTINATIONS_WEBHOOK_HEADER_PREFIX`**, or omit this header with **`DESTINATIONS_WEBHOOK_DISABLE_DEFAULT_EVENT_ID_HEADER`**.
+
+In **Standard Webhooks** mode, the same value is sent as the **`webhook-id`** header (default prefix `webhook-`, so typically **`Webhook-Id`**) per the [Standard Webhooks](https://www.standardwebhooks.com/) specification.
+
 ## Signatures
 
 ### Default Mode
@@ -171,18 +179,18 @@ PORTAL_ENABLE_WEBHOOK_CUSTOM_HEADERS=true
 
 {% tabs tabGroup="deployment" %}
 {% tab label="Managed" %}
-Configure webhook operator behavior using these keys in the Config API or in [Hookdeck Destinations settings](https://dashboard.hookdeck.com/settings/project/destinations): `DESTINATIONS_WEBHOOK_HEADER_PREFIX`, `DESTINATIONS_WEBHOOK_DISABLE_EVENT_ID_HEADER`, `DESTINATIONS_WEBHOOK_DISABLE_TIMESTAMP_HEADER`, `DESTINATIONS_WEBHOOK_DISABLE_TOPIC_HEADER`, `DESTINATIONS_WEBHOOK_DISABLE_SIGNATURE_HEADER`, `DESTINATIONS_WEBHOOK_MODE`, `DESTINATIONS_WEBHOOK_SIGNATURE_ALGORITHM`, `DESTINATIONS_WEBHOOK_SIGNATURE_ENCODING`, `DESTINATIONS_WEBHOOK_SIGNATURE_CONTENT_TEMPLATE`, and `DESTINATIONS_WEBHOOK_SIGNATURE_HEADER_TEMPLATE`.
+Configure webhook operator behavior using these keys in the Config API or in [Hookdeck Destinations settings](https://dashboard.hookdeck.com/settings/project/destinations): `DESTINATIONS_WEBHOOK_HEADER_PREFIX`, `DESTINATIONS_WEBHOOK_DISABLE_DEFAULT_EVENT_ID_HEADER`, `DESTINATIONS_WEBHOOK_DISABLE_DEFAULT_TIMESTAMP_HEADER`, `DESTINATIONS_WEBHOOK_DISABLE_DEFAULT_TOPIC_HEADER`, `DESTINATIONS_WEBHOOK_DISABLE_DEFAULT_SIGNATURE_HEADER`, `DESTINATIONS_WEBHOOK_MODE`, `DESTINATIONS_WEBHOOK_SIGNATURE_ALGORITHM`, `DESTINATIONS_WEBHOOK_SIGNATURE_ENCODING`, `DESTINATIONS_WEBHOOK_SIGNATURE_CONTENT_TEMPLATE`, and `DESTINATIONS_WEBHOOK_SIGNATURE_HEADER_TEMPLATE`.
 {% /tab %}
 {% tab label="Self-Hosted" %}
 ### Header Settings
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `DESTINATIONS_WEBHOOK_HEADER_PREFIX` | `x-outpost-` | Prefix for all webhook headers |
-| `DESTINATIONS_WEBHOOK_DISABLE_EVENT_ID_HEADER` | `false` | Disable the event ID header |
-| `DESTINATIONS_WEBHOOK_DISABLE_TIMESTAMP_HEADER` | `false` | Disable the timestamp header |
-| `DESTINATIONS_WEBHOOK_DISABLE_TOPIC_HEADER` | `false` | Disable the topic header |
-| `DESTINATIONS_WEBHOOK_DISABLE_SIGNATURE_HEADER` | `false` | Disable the signature header |
+| `DESTINATIONS_WEBHOOK_HEADER_PREFIX` | `x-outpost-` / `webhook-` | Prefix for system webhook headers (event id, topic, timestamp, signature). Unless overridden, defaults to **`x-outpost-`** when `DESTINATIONS_WEBHOOK_MODE` is `default` and **`webhook-`** when `standard`. |
+| `DESTINATIONS_WEBHOOK_DISABLE_DEFAULT_EVENT_ID_HEADER` | `false` | Disable the event ID header |
+| `DESTINATIONS_WEBHOOK_DISABLE_DEFAULT_TIMESTAMP_HEADER` | `false` | Disable the timestamp header |
+| `DESTINATIONS_WEBHOOK_DISABLE_DEFAULT_TOPIC_HEADER` | `false` | Disable the topic header |
+| `DESTINATIONS_WEBHOOK_DISABLE_DEFAULT_SIGNATURE_HEADER` | `false` | Disable the signature header |
 
 ### Signature Settings
 

docs/content/features/event-delivery.mdoc

@@ -3,7 +3,7 @@ title: "Event Delivery & Retries"
 description: "How Outpost delivers events, tracks attempts, and retries on failure."
 ---
 
-Outpost tracks each event, its status, and all delivery attempts. Delivery operates on an **at-least-once guarantee** — events may occasionally be re-delivered. Consumers should use the unique event ID to deduplicate when needed.
+Outpost tracks each event, its status, and all delivery attempts. Delivery operates on an **at-least-once guarantee** — events may occasionally be re-delivered. Consumers should deduplicate using the **event id** (the same value as publish `id` when you set one). For how that appears on webhook requests — headers, prefix, Standard Webhooks — see [Event ID header and idempotency](/docs/outpost/destinations/webhook#event-id-header-and-idempotency).
 
 ## Automatic Retries
 

docs/content/guides/migrate-to-outpost.mdoc

@@ -59,7 +59,7 @@ Webhooks are delivered via HTTP `POST` requests.
 
 ### Webhook Event HTTP Headers
 
-- `x-outpost-event-id`: A unique identifier for the event within the Outpost installation
+- `x-outpost-event-id`: The event id (same as publish `id` when you provide one). Use it as the **deduplication / idempotency key** for at-least-once delivery; the `x-outpost-` prefix is [configurable](/docs/outpost/destinations/webhook#operator-configuration).
 - `x-outpost-signature`: HMAC of the raw body (default `v0=<hex>`; operators may customize templates — see [Webhook destination](/docs/outpost/destinations/webhook#signature)).
 - `x-outpost-timestamp`: A Unix timestamp representing the time the event was generated
 - `x-outpost-topic`: The topic of the event. For example, `user.created`.

docs/content/publishing/events.mdoc

@@ -40,7 +40,7 @@ If you already publish events to a supported message queue, refer to the relevan
 
 | Field | Required | Description |
 |-------|----------|-------------|
-| `id` | No | Unique event ID. If omitted, generated by hashing topic, data, and timestamp. Providing an ID enables idempotency. |
+| `id` | No | Unique event ID. If omitted, Outpost assigns a server-generated id (UUID-style by default; configurable). Providing a stable ID enables **publish idempotency** (duplicate publishes are not re-queued while the key is remembered) and is the value receivers use to **deduplicate deliveries** — for webhooks, see [`X-Outpost-Event-Id` / header prefix](/docs/outpost/destinations/webhook#event-id-header-and-idempotency). |
 | `tenant_id` | Yes | The tenant to deliver the event to. Must match an existing tenant. |
 | `destination_id` | No | Force delivery to a specific destination, bypassing topic matching. |
 | `topic` | No | The event topic. Must match one of the configured topics if set. Assumed to match all topics if omitted. |

docs/content/quickstarts/hookdeck-outpost-curl.mdoc

@@ -38,6 +38,8 @@ curl --request PUT "$OUTPOST_API_BASE_URL/tenants/$TENANT_ID" \
   --header "Authorization: Bearer $OUTPOST_API_KEY"
 ```
 
+A successful tenant upsert returns **HTTP 200** if that tenant id already existed, or **HTTP 201** if Outpost created it. In shell scripts, treat **200 and 201** as success (do not require exactly `200`—automation that deletes the tenant first will usually see **201**).
+
 ## Create a webhook destination
 
 Subscribe the tenant to one or more topics you configured in the dashboard. Set `config.url` to an HTTPS endpoint you control.
@@ -59,6 +61,8 @@ curl --request POST "$OUTPOST_API_BASE_URL/tenants/$TENANT_ID/destinations" \
   }'
 ```
 
+On success, expect **HTTP 2xx** (often **201** the first time this destination is created for the tenant).
+
 To receive every configured topic on this destination, set `"topics": ["*"]` instead.
 
 ## Publish a test event
@@ -86,9 +90,18 @@ A `202` response means the event was accepted for delivery.
 
 ## Shell scripts: status codes and portability
 
-If you combine API response bodies with `curl --write-out '\n%{http_code}'`:
+When a script must **fail on unexpected HTTP status**, capture the code with `curl -o … -w '%{http_code}'` (response body to a file or `/dev/null`). Example for **tenant upsert**—accept **200** or **201** only:
+
+```sh
+code="$(curl -sS -o /dev/null -w "%{http_code}" --request PUT "$OUTPOST_API_BASE_URL/tenants/$TENANT_ID" \
+  --header "Authorization: Bearer $OUTPOST_API_KEY")"
+case "$code" in
+  200|201) ;;
+  *) echo "tenant upsert failed: HTTP $code" >&2; exit 1 ;;
+esac
+```
 
-- **Publish** success is **HTTP 202** (not only 200/201). Treat **202** as success in conditional checks.
+- **Publish** success is **HTTP 202** (not 200/201). Treat **202** as success in conditional checks.
 - **Portability:** GNU `head -n -1` (“all lines but the last”) is **not** available on macOS BSD `head`. Prefer splitting with **`sed '$d'`** (body) and **`tail -n 1`** (status), or another POSIX-friendly approach, so the same script runs on Linux and macOS.
 
 ## Verify delivery

docs/content/self-hosting/configuration.mdoc

@@ -114,11 +114,11 @@ Choose one for event log persistence:
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `DESTINATIONS_WEBHOOK_MODE` | `default` | Set to `standard` for Standard Webhooks compliance |
-| `DESTINATIONS_WEBHOOK_HEADER_PREFIX` | `x-outpost-` | Prefix for all webhook headers |
-| `DESTINATIONS_WEBHOOK_DISABLE_EVENT_ID_HEADER` | `false` | Disable the event ID header |
-| `DESTINATIONS_WEBHOOK_DISABLE_TIMESTAMP_HEADER` | `false` | Disable the timestamp header |
-| `DESTINATIONS_WEBHOOK_DISABLE_TOPIC_HEADER` | `false` | Disable the topic header |
-| `DESTINATIONS_WEBHOOK_DISABLE_SIGNATURE_HEADER` | `false` | Disable the signature header |
+| `DESTINATIONS_WEBHOOK_HEADER_PREFIX` | `x-outpost-` / `webhook-` | Prefix for system webhook headers (event id, topic, timestamp, signature). Unless overridden, defaults to **`x-outpost-`** when `DESTINATIONS_WEBHOOK_MODE` is `default` and **`webhook-`** when `standard`. |
+| `DESTINATIONS_WEBHOOK_DISABLE_DEFAULT_EVENT_ID_HEADER` | `false` | Disable the event ID header |
+| `DESTINATIONS_WEBHOOK_DISABLE_DEFAULT_TIMESTAMP_HEADER` | `false` | Disable the timestamp header |
+| `DESTINATIONS_WEBHOOK_DISABLE_DEFAULT_TOPIC_HEADER` | `false` | Disable the topic header |
+| `DESTINATIONS_WEBHOOK_DISABLE_DEFAULT_SIGNATURE_HEADER` | `false` | Disable the signature header |
 | `DESTINATIONS_WEBHOOK_SIGNATURE_ALGORITHM` | `hmac-sha256` | Signature algorithm |
 | `DESTINATIONS_WEBHOOK_SIGNATURE_ENCODING` | `hex` | Encoding: `hex` or `base64` |