Things every webhook has in common

These points apply to every feature in this guide unless the feature's own section says otherwise.

How the message is sent

• Crazytel sends an HTTP POST request to your URL.
• The body is JSON (Content-Type: application/json).
• Your URL should start with https:// and must be reachable from the public internet. Local or private network addresses (such as localhost or 192.168.x.x) will not work.

What your system should do when it receives one

• Reply with a success status (any 2xx, for example 200 OK or 204 No Content) as quickly as possible, ideally within a few seconds.
• If you need to do slow work (look up a CRM record, send emails, and so on), accept the webhook first, then do the work in the background. Slow replies are treated as failures and the message will be sent again.

Duplicates and order

• Webhooks are delivered "at least once". Occasionally you may receive the same event twice, for example after a retry. Use the event and call identifiers in the message to ignore duplicates.
• Events may arrive slightly out of order. Use the timestamps in the message rather than the order they arrive in.

Caller ID and dialled number

• Most webhooks include caller_id (who called) and original_did (the number they dialled) when those are known.
• These fields are optional. If a number is not known, the field is simply left out. This is normal and not an error.
• If the caller has withheld their number, caller_id contains the exact text Private Number.
• Numbers in webhooks are sent in international digit format without a plus sign, for example 61298786988 for (02) 9878 6988.

Security secret (signing)

• Most features let you set an optional secret. When a secret is set, each webhook includes a signature header. Your system can use it to confirm the message really came from Crazytel and was not changed along the way. See Verifying webhook signatures.
• Secrets are write-only. Once saved, Crazytel never shows them again. Store a copy somewhere safe. To change a secret, type a new one and save. To keep the current secret, leave the field blank.

Does a failed webhook affect the call?

No. If your system is down or returns an error, the call itself carries on as normal. Only the notification is affected.

Cost

There is no platform usage charge for sending webhooks. SMS alerts on the same features are billed per message segment.