Talvo can POST to your endpoint when things happen in your workspace. Because that endpoint is public, you should verify that a request genuinely came from us before acting on it.
The signature
Every delivery includes an HMAC-SHA256 signature of the raw request body, computed with your webhook's secret, in the header:
X-Talvo-Signature: <hex digest>
Verifying
- Take the raw request body — the exact bytes, before any JSON parsing. Re-serialising the parsed object will produce a different string and the signature will never match.
- Compute
HMAC-SHA256(raw_body, your_secret)as hex. - Compare it with the header using a constant-time comparison, not
==. - Reject the request if they differ.
Delivery behavior
Deliveries are best-effort and time out after a few seconds. Return a 2xx quickly and do the real work asynchronously — a slow endpoint will look like a failed one.
Recent deliveries and their responses are listed in Settings → Developers, so you can see what we sent and what your endpoint said.
Make your handler idempotent
Treat a repeat of the same event as a no-op. Networks retry, and an endpoint that charges a card or sends an email twice because it saw an event twice is a bug waiting to happen.
