Webhooks
Endpoints that receive signed events, how to test them and rotate their secret.
List webhook endpoints
The endpoints of the key's environment, newest first.
Create a webhook endpoint
Hometown checks the URL before it is saved. It must use HTTPS on port 443 or 1024 to 65535, resolve to public addresses only and answer without a redirect. An environment has at most 16 active endpoints. The answer carries the signing secret, which is not shown again. This operation takes no Idempotency-Key, so the secret is never stored for a replay.
Get a webhook endpoint
Get a webhook endpoint
Update a webhook endpoint
Change the URL, the description or the events, or enable or disable the endpoint. A new URL is checked like on create.
Delete a webhook endpoint
Deliveries still waiting for it are dropped, and its delivery history goes with it.
Rotate the signing secret
A new secret signs every delivery from now on. For 24 hours the previous secret signs too, as a second v1 in Hometown-Signature, so receivers can switch without missing an event.
Send a test event
Sends webhook.test to this endpoint, signed like any event, whatever events it subscribes to and even while it is disabled. It is tried once and never retried; GET the event to read the answer.
estimate.completed
An async estimate finished. data.object is the estimate. Answer 2xx within 10 seconds. Anything else is retried 8 times over about three days.
estimate.failed
An async estimate could not finish; nothing was charged. data.object is the estimate, with error. Answer 2xx within 10 seconds. Anything else is retried 8 times over about three days.
credits.low
Live credits fell to 20% or less of what your unexpired lots started with. Checked every hour, and sent once until credits are added. data.object is the balance. Answer 2xx within 10 seconds. Anything else is retried 8 times over about three days.
credits.exhausted
Live credits reached zero. data.object is the balance. Answer 2xx within 10 seconds. Anything else is retried 8 times over about three days.
api_key.rotated
A key was rotated. data.object is the new key; data.previous says when the old one stops working. Answer 2xx within 10 seconds. Anything else is retried 8 times over about three days.
api_key.expiring
A key with an expiry date stops working within 14 days. data.object is the key. Answer 2xx within 10 seconds. Anything else is retried 8 times over about three days.
api_key.suspicious_activity
A key behaved unlike itself. data.object is the key; data.anomaly says which rule and whether it was paused. Answer 2xx within 10 seconds. Anything else is retried 8 times over about three days.
webhook.test
Sent on request to one endpoint, even a disabled one, whatever events it listens to. data.object is the endpoint. It is tried once and never retried.