Glossary
Webhook
Also called: HTTP callback · Event notification · Web hook
A webhook is an HTTP request that one system sends automatically to an address another system chose, to report an event as soon as it happens.
Webhooks are the push side of an integration. Instead of asking an API every minute whether anything changed, the receiving system gets a POST request with the event. The receiver should answer quickly with a success status, or the sender will retry.
Because anyone can send a request to a public address, webhooks are usually signed. The sender computes an HMAC of the body with a shared secret, and the receiver recomputes it to confirm the request is genuine and recent. Receivers should also expect duplicates and handle each event once.
How Risti does it
In Risti, webhooks are added in Settings › Developers with Add endpoint (https only), choosing event groups: Messages, Conversations, Assignments, and Members and teams. Each delivery is signed with HMAC-SHA256 in the X-Risti-Signature header (sha256=…), computed over “timestamp.body”. The signing secret is shown once and can be rotated with 24 hours of grace.
Failed deliveries are retried 8 times over about 22.5 hours; after 5 failures in a row the endpoint is turned off and owners are emailed. Send a test and Recent deliveries help with set-up. Payloads never contain message bodies. For calls into Risti, see API key scopes.