Endpoints
POST /api/v1/webhook-subscriptions
Status: Live · Auth: Bearer or HMAC · Idempotent: No
url is an HTTPS URL, generates a 32-byte random secret, and creates a webhook subscription. Returns the full subscription including secret (shown once — store immediately). Subsequent GET responses never include the secret. Multiple subscriptions per tenant are supported; each has its own secret and event filter.
Create a new webhook subscription. The secret is shown once in the response — save it immediately.
Request body
HTTPS URL that Chert will POST events to. Must be publicly reachable. For local development, use
https://dev-inbox to record events without sending outbound HTTP.Event types to deliver to this subscription. Chert delivers
message.received, message.sent, message.failed, reaction.added, reaction.removed, and the legacy lead_reply summary. A subscription receives only the types it lists: an unlisted event is never sent to it, and the retry job does not send it later. Omit this field, or send an empty array, to receive every type, including types added later. See event types.Payload version for this subscription. When you omit it, the subscription uses
2026-05-04. Use 2026-11-16 for new integrations: it leaves the legacy transport field out of delivered payloads. See Event versions.Response fields
Stable subscription id. Also emitted in the
X-Webhook-Subscription-Id header on every delivery.Per-subscription HMAC secret. Shown once. Store it securely and use it to verify the
X-Webhook-Signature (or x-chert-signature) header on inbound deliveries. See Verifying signatures.GET /api/v1/webhook-subscriptions
Status: Live · Auth: Bearer or HMAC · Idempotent: Yes (read-only)
secret is never included.
List all subscriptions for your tenant, ordered newest first. secret is not included in list or get responses.
200 OK
updated_at reflects the last metadata change (URL, events, is_active, etc).
GET /api/v1/webhook-subscriptions/
Status: Live · Auth: Bearer or HMAC · Idempotent: Yes (read-only)
id scoped to your tenant. Same shape as a list row.
Return a single subscription. Same shape as a list row.
PATCH /api/v1/webhook-subscriptions/
Update one or more fields. Only the fields you include are modified.Request
"is_active": true to enable a subscription.
Fields accepted by PATCH:
DELETE /api/v1/webhook-subscriptions/
Permanently delete a subscription. Deliveries in-flight may still complete. Returns200 OK with the standard envelope:
200 OK
Signature verification
Each subscription generates its own secret, returned once in thePOST response. Use that subscription secret to verify deliveries — not your tenant signing_secret. The two are different values.
Every delivery carries both signature headers — verify whichever your stack reads more easily. Both compute the same HMAC:
.), not a colon. The body is the exact raw bytes Chert sent — do not parse-and-re-serialize before verifying (JSON middleware that mutates whitespace will silently invalidate the signature).
X-Webhook-Subscription-Id header identifies which subscription triggered the delivery, useful when multiple subscriptions point to the same endpoint with different secrets. This is a webhook delivery header from Chert to your endpoint; it is separate from x-chert-tenant, which your application sends when calling Chert APIs.
Delivery and replay
Chert records every event before outbound delivery. If multiple active subscriptions match an event, Chert attempts each destination and records one delivery attempt per subscription on the event row.
Use
GET /api/v1/events to inspect delivery status and POST /api/v1/events/{id}/replay to re-deliver a stored event. To replay to one subscription, pass ?subscription_id=<subscription_id>.
Common pitfalls
See also
Event versions
Setversion to 2026-11-16 when creating a subscription to receive event payloads without the legacy transport field. Event IDs, message content and signature headers are unchanged. This version applies to live delivery, retries and replay. Existing subscriptions keep their selected version; a subscription created without version uses 2026-05-04 for compatibility. The webhook_version field inside each payload reads 2026-05-04 under both versions, so read the subscription’s version to know which one applies. Change it on an existing subscription with PATCH.
Diagnostic text may become more general without changing the error code or retry guidance. Use codes and status fields for program logic, and retain the trace ID for troubleshooting.
