# Webhooks API

Source: https://neondeerdata.com/docs/api/webhooks/

Receive signed notifications about Duplicate Detection and scheduled runs.

## Set up an endpoint

Webhooks require alpha access and access to the event families you select. Use an HTTPS receiver you control. [Create an endpoint](https://neondeerdata.com/docs/api/webhooks/endpoints/), save its signing secret securely, and send a verification delivery. The endpoint must be verified before it receives events.

The REST routes and MCP actions for creating an endpoint or rotating its signing secret return the secret in their response. Treat that response as sensitive: save the secret in your receiver’s secrets manager, and keep it out of screenshots, shared conversations, and logs. Do not expect a separate claim link in Neon Deer.

## Verify each delivery

Neon Deer signs the exact request-body bytes using the Standard Webhooks header format:

| Header              | Meaning                                            |
| ------------------- | -------------------------------------------------- |
| `webhook-id`        | The event identifier, preserved across retries.    |
| `webhook-timestamp` | This delivery attempt's Unix timestamp in seconds. |
| `webhook-signature` | Space-separated `v1,<signature>` values.           |

Decode the base64 part after the signing secret's `whsec_` prefix to obtain the HMAC key. Compute HMAC-SHA256 over the bytes of `<webhook-id>.<webhook-timestamp>.` followed by the unmodified raw request body. Compare its base64 value against a presented `v1` signature using a constant-time comparison.

Check that the timestamp is recent using your receiver's clock-tolerance policy. Verify before parsing or processing the JSON body. Parsing and reserializing JSON before verification changes the signed bytes and can break verification.

## Process safely

Store the event identifier so repeated deliveries do not repeat your application's action. Do not depend on delivery order. A notification tells you that something changed; read the current resource or operation to determine the latest state.

[Delivery endpoints](https://neondeerdata.com/docs/api/webhooks/deliveries/) let you inspect attempts and request a replay when allowed. A replay can repeat a delivery, so your receiver still needs duplicate protection.

## Rotate or transfer

The [endpoint reference](https://neondeerdata.com/docs/api/webhooks/endpoints/) covers secret rotation, verification, and ownership transfer. Inspect `previous_secret_expires_at` for an overlap rotation rather than assuming the old secret remains valid. An immediate rotation stops the previous secret at once.

Transferring an endpoint stops its signing secrets and requires the receiving key to issue its own secret and verify the endpoint again. Keep secrets in your receiver's secrets manager and out of chat, screenshots, and logs.