Skip to main content

Ingest a signed webhook event

POST 
/ingest/webhooks/:source_id/events

Producers POST one signed event per request. The body is HMAC-verified against the active signing secrets registered on the source_id, then enqueued for processing.

Idempotency is on event_id. A second POST with the same event_id returns 200 (not 202) with duplicate: true, and enqueues nothing. The status is the quickest way to tell the two apart: 202 means work was enqueued, 200 means the event was received and deliberately not acted on — a duplicate, or a type this source is not allowed to send. Both are successes; neither should be retried.

Required headers: X-Kudos-Signature, X-Kudos-Event-Id, X-Kudos-Event-Type, X-Kudos-Schema-Version. See the Webhook signing guide for the wire format.

Request​

Responses​

Received, but nothing was done — and that is a success, not a problem to retry.

Two cases, distinguished by the body, never by the status:

  • duplicate: true — this event_id has been seen. The original result stands; nothing was applied twice. This is the answer to your own retry after a timeout.
  • ignored: true — the event type is not in this source's allowed_event_types. That list is deny-by-default: while it is empty, every event lands here and does nothing. If your events are accepted but nothing changes in the CRM, check this first.

Treat any 2xx as delivered and stop retrying. The distinction between 202 and 200 is informational — it tells you whether work was enqueued, not whether you succeeded.