Skip to main content

Webhooks

Movoice sends an HTTP POST to your URL when one of your calls changes. Each request is signed with a secret that only that URL has.

Set up an endpoint

  1. In the dashboard, open Developer (/admin/developer) and add a webhook.
  2. Enter your URL. It must start with https://.
  3. Pick the events it should get.
  4. Copy the secret shown once when you save. You can reveal or rotate it later on the same page.
  5. Press Test to POST a sample call.completed to that URL, signed the same way real deliveries are.

Events

These are all the events Movoice sends today:

The payload

Every event has the same shape. Fields that do not apply to that event are left out.
direction is inbound, outbound or web. event_id is the same on every retry of one event, so you can use it to ignore duplicates.

Headers

Check the signature

The signature is an HMAC-SHA256 of <timestamp>.<raw body> with your endpoint’s secret. Use the raw body exactly as it arrived, before any JSON parsing.
Reject a request whose timestamp is far from your clock, so an old request can’t be replayed.

Answer quickly, and retries

  • Answer with any 2xx within 15 seconds. Anything else counts as a failure.
  • A failure is tried twice more straight away (after 0.5 s and 2 s).
  • If it still fails, it is retried later: after 1 minute, 5 minutes, 15 minutes, 1 hour, 3 hours and 6 hours. Then it is given up.
  • Every delivery and its result is listed on the Developer page. You can replay one from there.
  • After 15 failures in a row the endpoint is paused, and you get an email and a bell. Events for a paused endpoint are held, not lost: turn it back on and the held events are sent.
  • An endpoint you switch off yourself keeps nothing while it is off.