# Overview

Shace sends events to your endpoints as they happen: your listings going live or coming off the market and, with [full integration](/receiving-leads), new leads and what happens to them. [Events](/webhooks/events) lists every event with its payload. [Receiving leads](/receiving-leads) walks through a receiver for a CRM.

## Endpoints

Your organization's developers add endpoints under **Developer > Webhooks** in the Shace dashboard, where you also send test events and see the latest deliveries. Each one gets a signing `secret`, starting with `whsec_`, that you receive once when the endpoint is added, so store it with your receiver right away. Endpoints are per environment: the sandbox dashboard has its own, with their own secrets.

Your organization can have up to 5 endpoints, and each gets every event your organization receives. Deal events (`deal.*`) are sent only with full integration; listing events and test events are sent either way.

To rotate a secret, add a new endpoint, switch your receiver over, and delete the old one. Meanwhile both endpoints get every event, with the same `id`. Deleting an endpoint gives up on the deliveries still waiting for it, so keep the old one until its delivery log shows nothing outstanding. `GET /webhooks` lists your endpoints; `eventTypes: null` there means the endpoint gets every event. The [Webhook endpoints](/reference/webhook-endpoints) section of the reference has the calls.

## Delivery

Each event is a JSON `POST` with the body `{ id, type, createdAt, data }` and three headers:

| Header | Value |
| --- | --- |
| `webhook-id` | The event id, the same as `id` in the body and on every retry. |
| `webhook-timestamp` | When this attempt was sent, in Unix seconds. |
| `webhook-signature` | `v1,` followed by the signature. |

Answer with any `2xx` within 10 seconds. If processing takes longer, store the event, answer, and process it afterwards: a `2xx` is final and Shace stops retrying it. Redirects are not followed. Events usually arrive within 10 seconds of what caused them.

An endpoint URL must be `https` on the default port, on a public hostname, without credentials, and at most 2048 bytes.

## Verifying signatures

Signatures follow [Standard Webhooks](https://www.standardwebhooks.com), which has verification libraries for most languages, .NET included. To verify by hand:

1. Base64-decode the part of the secret after `whsec_`. That is the key.
2. Compute HMAC-SHA256 over `<webhook-id>.<webhook-timestamp>.<raw body>` with that key, and base64-encode it.
3. Compare the result, in constant time, with the part after `v1,` in `webhook-signature`.
4. Reject timestamps more than 5 minutes off, so a captured request cannot be replayed later.

Verify against the raw body as received. A body that was parsed and serialized again will not match.

## Retries

Anything but a `2xx` in time is retried after 1 minute, 5 minutes, 30 minutes, 2 hours, 5 hours, 10 hours and 10 hours: 8 attempts over about 28 hours. After that the event is given up and Shace support is alerted.

An endpoint that was down for less than that gets every event it missed, each at its next scheduled retry. A delivery that was given up can be sent again from **Developer > Webhooks** once your receiver is back.

## Duplicates and order

Delivery is at least once, so the same event can arrive twice: drop repeats by `id`.

Events can arrive out of order: after a retry, or when two happen within seconds of each other, since deliveries go out in parallel. `createdAt` does not guarantee order either, so treat an event as a signal that the deal changed. When order matters, read the current state with `GET /deals/{id}`.

New event types can be added at any time. Answer an event type you do not know with a `2xx` and ignore it.

## Testing

`POST /webhooks/{id}/test` sends a signed `webhook.test` event to that endpoint, once, without retries. It arrives within seconds. Your organization can send 10 test events in 10 minutes; over that, the call answers `429` with `Retry-After` in seconds.
