What gets signed
With signing on, every webhook your account sends is signed:- Post-call webhooks from your agents’ Post-Call Analysis → Integrations.
- The per-call
webhook_urlyou pass to the call API. - Test sends from the Test button, and retries from Integration Logs.
The signed message is the timestamp and the body joined with nothing in between:
raw_body is the exact bytes Osvi sent. For GET and DELETE webhooks there is no body, so the message is just the timestamp.
Turn on signing
- Go to Settings → Webhook signing.
- Switch on Sign webhooks.
- Confirm that you understand this is a critical security setting, then enter your password again. If you sign in to Osvi with Google, sign in with Google again instead.
- Copy the secret that appears and store it on your server, for example as
OSVI_WEBHOOK_SECRET.
Verify a request
For every webhook:- Read the raw request body before parsing it as JSON. Parsing and re-serializing changes the bytes, and the signature won’t match.
- Reject the request if
X-Signature-Timestampis missing or more than 5 minutes away from your server’s clock. This stops someone replaying an old request. - Compute the HMAC-SHA256 of the timestamp followed by the raw body, with your secret, as lowercase hex.
- Compare it with
X-Signatureusing a constant-time comparison. IfX-Signature-Previousis present, accept a match on either header. - Respond with a
401and ignore the payload if nothing matches.
Check your code
Run your verification against these values. It should produce the signature shown.
The timestamp in this example is fixed, so skip the 5-minute check while you test.
Rotate the secret
Rotate the secret if it may have leaked, or as routine hygiene.- In Settings → Webhook signing, click Rotate secret and confirm it’s you (password or Google).
- Within a minute, Osvi starts signing with the new secret. For the next hour, each webhook also carries
X-Signature-Previous, signed with your old secret, so your server keeps accepting requests while you deploy the new one. - Wait at least a minute after rotating, then update your server with the new secret.
- If the old secret leaked, click Expire it now to stop accepting it immediately instead of waiting out the hour.
X-Signature and X-Signature-Previous, as the examples above do, a rotation never rejects a genuine request.
