Register a webhook
signingSecret — save it immediately, it is returned once only.
Available events
Event payload shape
Torpedo sends aPOST with a JSON body. Every event uses the same envelope:
The request also carries these headers:
data by event
Email
SMS
statandproviderStatusare the operator’s delivery status, for exampleUNDELIV,EXPIREDorREJECTD.providerErrorCodeis the operator’s error code, ornullwhen it didn’t send one.failureCategoryis one ofundeliverable,expired,rejected,deletedorunknownforsms.undelivered, andsubmission_errorforsms.failed.
undeliverable or rejected) also adds the number to your
suppression list.
Example sms.undelivered:
verification.* event includes verificationId, to and clientRef (your reference from
the start request, or null). Some events add more fields:
channeliswhatsapporsms.errorCodeis the WhatsApp error code, for example131026when the number isn’t on WhatsApp.- For WhatsApp,
errorCategoryis one ofrecipient_unreachable,throttled,transient,invalid_request,expiredorplatform. For SMS it uses the same categories assms.undelivered. - In
verification.fallback,reasonis the WhatsApperrorCategorythat triggered the fallback.
verification.fallback:
Use the ID in
data to fetch the full record, for example GET /api/v1/sms/{smsId},
GET /api/v1/emails/{emailId} or GET /api/v1/verify/{verificationId}.
Verifying the signature
Every request from Torpedo includes anX-Signature header:
Delivery retries
Torpedo retries failed webhook deliveries up to 7 times over about 27 hours: after 5 seconds, 5 minutes, 30 minutes, 2 hours, 5 hours, 10 hours and 10 hours. Your endpoint should:- Return
2xxwithin 5 seconds - Be idempotent. The same event may be delivered more than once, always with the same
id
View delivery history via
GET /api/v1/webhooks/{id}/deliveries.