React in real time with signed webhooks
Subscribe to verification events, receive signed JSON payloads, and rely on automatic retries with exponential backoff.
Event types
Every webhook delivery includes a stable event type. Subscribe to the ones you need.
| Event | Description |
|---|---|
| otp.sent | An OTP has been queued and dispatched to the chosen channel. |
| otp.delivered | The provider confirmed delivery to the user's device. |
| otp.verified | The user submitted the correct code and was successfully verified. |
| otp.failed | Delivery or verification failed — see the payload for the reason. |
| otp.expired | The OTP expired before the user submitted a code. |
Payload schema
All webhook bodies share the same envelope: an event id, type, timestamp, and a typed data object.
json
{
"id": "evt_2KqLxY9z3a",
"type": "otp.verified",
"created_at": "2026-05-03T10:14:22Z",
"data": {
"id": "otp_8f2c1a9b4d",
"channel": "sms",
"phone": "+9665XXXXXXXX",
"status": "verified",
"verified_at": "2026-05-03T10:14:21Z"
}
}Verify the signature
Every request carries an Authentica-Signature header. Verify it with HMAC-SHA256 and a timing-safe comparison before trusting the body.
typescript
import crypto from "node:crypto";
// Header sent by Authentica on every webhook delivery:
// Authentica-Signature: t=1714723200,v1=4f8c…
export function verifyWebhook(rawBody: string, header: string, secret: string) {
const parts = Object.fromEntries(header.split(",").map(p => p.split("=")));
const signedPayload = `${parts.t}.${rawBody}`;
const expected = crypto
.createHmac("sha256", secret)
.update(signedPayload)
.digest("hex");
const ok = crypto.timingSafeEqual(
Buffer.from(expected, "hex"),
Buffer.from(parts.v1, "hex"),
);
if (!ok) throw new Error("Invalid signature");
return JSON.parse(rawBody);
}Retry policy
We treat any non-2xx response (or a timeout) as a failure and retry automatically.
- Exponential backoff: retries at 30s, 2m, 10m, 1h, and 6h.
- Up to 5 attempts over 24 hours before the event is dropped.
- Each retry uses a fresh signature with the current timestamp.
- Failed deliveries are visible in the dashboard for manual replay.