Webhooks

​

Set a callback URL

{
  "to": "+14155552671",
  "callback": "https://example.com/webhooks/otpbay"
}

​

When webhooks are sent

​

Payload

{
  "sid": "VE6650c3a1b2c3d4e5f6a7b8c9",
  "channel": "verify",
  "status": "approved",
  "to": "+14155552671",
  "cost": "0.04",
  "metadata": { "user_id": "usr_1042" },
  "error": null,
  "date_created": "2026-09-26T10:15:01.873Z",
  "date_updated": "2026-09-26T10:15:40.530Z"
}

​

Respond to webhooks

​

Handle webhooks safely

• Treat webhooks as hints. Webhooks aren’t signed. Before acting on one — for example, marking a phone number verified — fetch the object from the API with its sid and check the status there.
• Use a hard-to-guess URL. Add a secret to the path, such as /webhooks/otpbay/4f9c2a..., and reject requests to any other path.
• Expect duplicates and any order. Key your processing on sid and status, and ignore updates you’ve already handled.
• Respond fast. Acknowledge right away and do slow work in a background job.

app.post("/webhooks/otpbay/:secret", express.json(), async (req, res) => {
  if (req.params.secret !== process.env.OTPBAY_WEBHOOK_SECRET) {
    return res.sendStatus(404);
  }
  res.sendStatus(200);

  const { sid, channel } = req.body;
  if (channel !== "verify") return;

  // Confirm with the API before trusting the payload.
  const r = await fetch(`https://api.otpbay.com/v1/verifications/${sid}`, {
    headers: { Authorization: `Bearer ${process.env.OTPBAY_API_KEY}` },
  });
  const verification = await r.json();
  await handleVerification(verification);
});