otp.verified Webhook — OTP Verification Notification

The otp.verified webhook is an outbound HTTP request that OTP.ID sends to your server when an OTP transaction reaches the verified state. Unlike the API endpoints documented elsewhere, you do not call this — you receive it. To activate it, contact the OTP.ID team to register your webhook URL and receive your webhook_secret (self-service configuration from the dashboard is coming soon). Every incoming request carries a cryptographic signature you must validate before trusting the payload.

Direction and Trigger

OTP.ID sends a POST request to your configured webhook URL whenever a transaction is verified — either by a successful call to POST /v3/verify or by an automatic token match in a whatsapp_inbound flow. The delivery is asynchronous: the webhook fires after OTP.ID records the verification and may arrive a few seconds after the verified status is set.

If no webhook URL is registered for your account, this event is silently dropped. The webhook is a no-op until you register a URL.

Request from OTP.ID

OTP.ID sends the following request to your endpoint:

Method: POST
Content-Type: application/json

Headers

Header	Type	Description
`X-OTPID-Timestamp`	string	Unix timestamp (seconds) at which OTP.ID sent this request.
`X-OTPID-Signature`	string	HMAC-SHA256 hex signature. Verify this before processing the payload.

Payload Fields

string

Always "otp.verified". Use this field if your endpoint handles multiple event types.

string

The verified transaction ID (e.g. "OTP20260807ABCD000001").

string

The external_id you sent when creating the transaction, echoed back so you can match this event to your own record without an extra lookup. Always present — an empty string ("") when you did not send one. See Idempotency.

string

The delivery channel used for the transaction (e.g. "whatsapp", "sms", "email").

string

The destination phone number or email address associated with the transaction.

string

The datetime at which verification occurred, in YYYY-MM-DD HH:MM:SS format (WIB, UTC+7).

Payload Example

{
  "event": "otp.verified",
  "otp_id": "OTP20260807ABCD000001",
  "external_id": "order-8821",
  "channel": "whatsapp",
  "number": "6281234567890",
  "verified_at": "2026-08-07 10:01:30"
}

The payload never contains the OTP code, any hash or salt of the code, or inbound tokens. It carries only the identity and outcome of the transaction.

Signature Verification

Every request from OTP.ID includes an X-OTPID-Signature header. Always verify this signature before acting on the payload — it protects you against spoofed requests. Algorithm (HMAC-SHA256):

Read the X-OTPID-Timestamp header value.
Read the raw, unparsed request body as a string (before JSON parsing).
Concatenate: "{timestamp}." + raw_body
Compute HMAC-SHA256 of that string using your webhook_secret (provided when your webhook URL is registered).
Compare the result (hex-encoded) with X-OTPID-Signature using a constant-time comparison to prevent timing attacks.

Use the raw request body — not a serialized version of the parsed JSON — to compute the signature. JSON serialization can alter whitespace or key ordering, causing valid signatures to fail.

const crypto = require('crypto');

app.post('/webhooks/otp', express.raw({ type: 'application/json' }), (req, res) => {
  const timestamp = req.headers['x-otpid-timestamp'];
  const signature = req.headers['x-otpid-signature'];
  const rawBody = req.body.toString();

  const message = `${timestamp}.${rawBody}`;
  const expected = crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(message)
    .digest('hex');

  const isValid = crypto.timingSafeEqual(
    Buffer.from(expected, 'hex'),
    Buffer.from(signature, 'hex')
  );

  if (!isValid) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const event = JSON.parse(rawBody);
  // Process event.otp_id, event.channel, event.verified_at ...
  res.sendStatus(200);
});

import hmac
import hashlib
from flask import Flask, request

app = Flask(__name__)

@app.route('/webhooks/otp', methods=['POST'])
def handle_webhook():
    timestamp = request.headers.get('X-OTPID-Timestamp')
    signature = request.headers.get('X-OTPID-Signature')
    raw_body = request.get_data(as_text=True)

    message = f"{timestamp}.{raw_body}"
    expected = hmac.new(
        WEBHOOK_SECRET.encode(),
        message.encode(),
        hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(expected, signature):
        return {'error': 'Invalid signature'}, 401

    event = request.get_json(force=True)
    # Process event['otp_id'], event['channel'], event['verified_at'] ...
    return '', 200

Retry Policy

If your endpoint returns a non-2xx response or OTP.ID cannot reach it within the timeout, OTP.ID retries the delivery automatically. Delivery is attempted up to 3 times in total:

Attempt	Delay before this attempt
1st attempt	immediate
2nd attempt	1 second after the 1st fails
3rd attempt	2 seconds after the 2nd fails

Each attempt has a 10-second timeout, and X-OTPID-Timestamp (and therefore the signature) is regenerated per attempt. After the 3rd failed attempt the event is dropped and not retried further.

Respond with an HTTP 2xx status code as quickly as possible — within the 10-second timeout. If your processing logic is slow (database writes, downstream API calls, etc.), acknowledge receipt immediately and process the event asynchronously in a background job or queue.

Checklist for Your Endpoint

✅ Parse the raw body before any middleware that mutates it
✅ Validate X-OTPID-Signature using constant-time comparison
✅ Optionally reject requests where X-OTPID-Timestamp is too far in the past (e.g. > 5 minutes) to guard against replay attacks
✅ Return HTTP 200 immediately; process async if needed
✅ Treat duplicate deliveries of the same otp_id idempotently — retries may cause the same event to arrive more than once

Account & Billing

OTP

Webhooks

otp.verified Webhook — OTP Verification Notification

Direction and Trigger

Request from OTP.ID

Headers

Payload Fields

Payload Example

Signature Verification

Retry Policy

Checklist for Your Endpoint

​Direction and Trigger

​Request from OTP.ID

​Headers

​Payload Fields

​Payload Example

​Signature Verification

​Retry Policy

​Checklist for Your Endpoint

Direction and Trigger

Request from OTP.ID

Headers

Payload Fields

Payload Example

Signature Verification

Retry Policy

Checklist for Your Endpoint