Overview
Shace sends events to your endpoints as they happen: your listings going live or coming off the market and, with full integration, new leads and what happens to them. Events lists every event with its payload. 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 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, which has verification libraries for most languages, .NET included. To verify by hand:
- Base64-decode the part of the secret after
whsec_. That is the key. - Compute HMAC-SHA256 over
<webhook-id>.<webhook-timestamp>.<raw body>with that key, and base64-encode it. - Compare the result, in constant time, with the part after
v1,inwebhook-signature. - 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.