Welcome Offer: 100 free verifications when you register!Claim your 100 free verifications
Authentica

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.

EventDescription
otp.sentAn OTP has been queued and dispatched to the chosen channel.
otp.deliveredThe provider confirmed delivery to the user's device.
otp.verifiedThe user submitted the correct code and was successfully verified.
otp.failedDelivery or verification failed — see the payload for the reason.
otp.expiredThe 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.