Outbound webhooks

A webhook is how your own systems find out something happened without asking repeatedly. You give us a URL, subscribe to events, and we POST JSON the moment they occur.

Two details matter more than the rest: verify the signature, and make your endpoint tolerant of repeats.

Who this is for

Developers and technical integrators.

Before you start

• An HTTPS endpoint you control that can accept a POST.
• Permission to manage webhooks.
• Somewhere to store the signing secret securely.

Verify the signature over the raw bytes
Each delivery carries an HMAC signature computed over the exact payload bytes using a secret scoped to your account. Verify it against the raw request body before parsing — if your framework parses and re-serialises the JSON first, the bytes change and the signature will not match. This is the single most common integration bug, and skipping verification means anyone who learns your URL can post to it.

Set up a webhook

1. Stand up an endpoint
   It needs to accept a POST and return quickly. Do the real work asynchronously — a slow endpoint causes timeouts and retries.
2. Subscribe to the events you need
   Subscribe narrowly. Every event you take and discard is load on both sides for nothing.
3. Store the signing secret
   Keep it somewhere secret. It is what proves a request came from us.
4. Verify before you trust
   Compute the HMAC over the raw body and compare before parsing or acting. Reject anything that does not match.
5. Make handling idempotent
   Retries mean you can receive the same event more than once. Handle a repeat as a no-op rather than as a second thing happening.
6. Return 2xx fast
   Acknowledge quickly and process afterwards. Transient failures are retried with backoff, so a brief outage does not lose the event — but a permanently slow endpoint looks like a permanent failure.

What you get

• Your systems notified the instant something changes, with no polling.
• Cryptographic proof that a delivery came from your account.
• Automatic retries with backoff, so a brief blip does not lose an event.
• A general-purpose route to any tool the catalogue does not cover.

Frequently asked questions

How do I know a webhook really came from KudosCRM?

Every delivery carries an HMAC signature computed over the exact payload bytes using a secret scoped to your account. Recompute it over the raw body and compare.

Why does my signature check fail even though the payload looks right?

Almost always because something parsed and re-serialised the JSON before you verified. The signature is over the exact bytes — verify against the raw body.

What happens if my endpoint is down?

Transient failures such as timeouts and dropped connections are retried automatically with backoff, so a short outage does not lose the event.

Could I receive the same event twice?

Yes — that is a normal consequence of retries. Make your handler idempotent so a repeat is harmless.