POST with:
Verify against the bytes you received, not a re-encoded JSON object. The signing secret is shown and rotatable on the webhooks page.
Payload
The signed body is compact JSON (no extra spaces, no trailing newline).json.Marshal pretty-print or a parser that re-encodes the object will not match X-Robase-Signature. data field order follows the structs below (id, phone_number, country_code, …). timestamp is UTC RFC3339 with whole seconds.
OTP events:
otp.delivered uses "status":"delivered". otp.failed adds "reason" (a stable token) and "refunded" (boolean) when known.
SMS events include message. <, >, and & in the body are not HTML-escaped:
sms.blocked also sets data.antispam (is_spam, score, category, reason).
Credit events:
credit_balance.topped_up omits threshold. Dashboard test-fire sets "test":true on credit samples so you can ignore them. Production credit events omit test.
Events
Frominternal/core/webhook.go (also the dashboard picker):
otp.failed, sms.failed and sms.blocked also carry reason (a stable token) and refunded (a boolean read from the credit ledger) in data when they are known. See Delivery timeline for the tokens.
Dashboard test-fire for credit_balance.* uses the same data shape (workspace_id, balance, optional threshold) and sets "test": true so you can ignore samples.
Respond with 2xx. A timeout, a 408, a 429 or any 5xx is retried with backoff, up to 3 attempts. Every other 4xx reads as a refusal and is not retried — fix the endpoint, then retry the delivery from the dashboard.
When an endpoint keeps failing
The webhooks page grades your endpoint on the last 24 hours of deliveries and counts the failures in a row. Every attempt in the delivery log carries the exact JSON we signed, theX-Robase-Signature we sent with it, and your endpoint’s own reply — enough to debug a rejection without adding logging on your side.
While deliveries are failing, we email the workspace’s owners, admins and finance members every six hours with the count and a link to the log. After 20 failures in a row we switch the endpoint off and email you at once: events stop being delivered so the queue does not fill with events nobody receives. Turn it back on from the webhooks page once the endpoint is fixed — the failure count resets and deliveries resume from the next event. Events that fired while it was off are not replayed.
See Webhook security for verification code.