Skip to main content
Osvi can sign every webhook it sends you with a secret that only your account and Osvi know. Your server recomputes the signature and drops any request that doesn’t match, so nobody else can send you fake call results. Signing is off by default. Until you turn it on, webhooks are sent without a signature, exactly as before.

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_url you pass to the call API.
  • Test sends from the Test button, and retries from Integration Logs.
Each signed request carries these headers: 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

  1. Go to Settings → Webhook signing.
  2. Switch on Sign webhooks.
  3. 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.
  4. Copy the secret that appears and store it on your server, for example as OSVI_WEBHOOK_SECRET.
Signing starts within a minute. Admins and members can turn signing on and manage the secret; Support users can see whether it’s on. Each sub-account has its own secret and its own switch. You can reveal the secret again at any time from the same card. If you haven’t confirmed it’s you in the last 5 minutes, you’re asked to enter your password or sign in with Google again.
Treat the secret like a password. Anyone who has it can send your server requests that look like they came from Osvi. Never put it in client-side code or a public repository.

Verify a request

For every webhook:
  1. Read the raw request body before parsing it as JSON. Parsing and re-serializing changes the bytes, and the signature won’t match.
  2. Reject the request if X-Signature-Timestamp is missing or more than 5 minutes away from your server’s clock. This stops someone replaying an old request.
  3. Compute the HMAC-SHA256 of the timestamp followed by the raw body, with your secret, as lowercase hex.
  4. Compare it with X-Signature using a constant-time comparison. If X-Signature-Previous is present, accept a match on either header.
  5. Respond with a 401 and 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.
  1. In Settings → Webhook signing, click Rotate secret and confirm it’s you (password or Google).
  2. 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.
  3. Wait at least a minute after rotating, then update your server with the new secret.
  4. If the old secret leaked, click Expire it now to stop accepting it immediately instead of waiting out the hour.
If your server checks both X-Signature and X-Signature-Previous, as the examples above do, a rotation never rejects a genuine request.

Turn off signing

Switch off Sign webhooks in Settings → Webhook signing. Within a minute, webhooks are sent without a signature. If your server requires a signature, it will start rejecting them, so update it first. Your secret is kept. Turning signing back on uses the same secret, so you don’t need to change anything on your server.