Webhooks Overview
Truto provides webhooks which can notify you of interesting events happening in your Truto account. They can also notify you about changes happening in the third party app integrations where Truto receives the webhook events from the integrations and proxies them to your endpoint in a unified format as record:* events.
Webhook endpoints
HTTPS and POST
Use an HTTPS URL for every webhook endpoint so event payloads are encrypted in transit. The endpoint must accept the POST method.
Each environment has a limit on the number of webhooks it can hold. Creating one past the limit returns a 400 error.
Security
SHA256 Signature
Every request made to a webhook endpoint has x-truto-signature header which contains the SHA256 HMAC of the request body being sent. This helps you make sure that the requests are originating from Truto. The SHA256 HMAC uses a secret string (UUID) which is shared with you when the webhook is created. See creating webhook endpoint.
To prevent replay attacks, you can check the created_at attribute of the request body and ignore the webhook event if it's longer than a certain timeframe, there is also a unique id in the request body for each webhook event.
Retries
Webhook endpoints need to respond with any 2XX status code. Truto makes up to five delivery attempts: one immediately, then retries after 30 seconds, 1 minute, 1.5 minutes, and 2 minutes, all inside a five-minute window. After the last attempt the event is marked as failed.
Network errors and other non-2XX responses are retried. 400, 404, and 413 responses are treated as permanent and are not retried.
Logging
Every webhook delivery is logged. View deliveries in the Truto dashboard under Logs → Webhook, or fetch them with GET /log?log_type=webhook.