Webhooks

SecureOTP can notify your backend with real-time HTTP callbacks when key events occur. Configure a webhook URL and SecureOTP will POST a JSON payload to it whenever a relevant event happens.

Configuration

Set your webhook URL from Settings in the Console, or via the settings API:

bash

curl -X PUT https://otp.applicanity.com/api/settings \
  -H "Authorization: Bearer <session_token>" \
  -H "Content-Type: application/json" \
  -d '{ "webhookUrl": "https://your-server.com/hooks/secureotp" }'

Once set, all events for your account are delivered to that URL. Clear the field to stop receiving webhooks.

Notification Settings

In addition to the webhook URL, you can toggle which events trigger notifications:

| Setting | Default | Description | | --- | --- | --- | | notifyLowCredit | false | Notify when your balance falls below a threshold | | notifyWeeklyReport | false | Receive a weekly summary of your OTP activity | | notifyNewLogin | false | Alert when a new login occurs on your account | | notifyLoginActivity | false | Log all login events |

Configure these via the same settings endpoint:

bash

curl -X PUT https://otp.applicanity.com/api/settings \
  -H "Authorization: Bearer <session_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": "https://your-server.com/hooks/secureotp",
    "notifyLowCredit": true,
    "notifyWeeklyReport": true
  }'

Payload Format

All webhook events share a common envelope:

json

{
  "event": "otp.delivered",
  "timestamp": "2026-06-09T10:00:01.000Z",
  "data": { }
}

| Field | Type | Description | | --- | --- | --- | | event | string | Event name (see event types below) | | timestamp | string | ISO 8601 timestamp when the event occurred | | data | object | Event-specific payload |

Event Types

`otp.delivered`

Fired after an OTP is sent successfully.

json

{
  "event": "otp.delivered",
  "timestamp": "2026-06-09T10:00:01.000Z",
  "data": {
    "phone": "+628123456789",
    "channel": "SMS",
    "expiresAt": "2026-06-09T10:05:01.000Z"
  }
}

`otp.verified`

Fired after an OTP is verified successfully.

json

{
  "event": "otp.verified",
  "timestamp": "2026-06-09T10:01:30.000Z",
  "data": {
    "phone": "+628123456789",
    "channel": "WHATSAPP"
  }
}

`balance.low`

Fired when your credit balance drops below the warning threshold (requires notifyLowCredit: true).

json

{
  "event": "balance.low",
  "timestamp": "2026-06-09T10:02:00.000Z",
  "data": {
    "balance": 1200,
    "threshold": 2000
  }
}

Receiving Webhooks

Your endpoint must:

Accept POST requests
Return a 2xx status within 10 seconds
Handle JSON bodies

A minimal Express.js receiver:

javascript

app.post('/hooks/secureotp', express.json(), (req, res) => {
  const { event, data } = req.body

  if (event === 'otp.verified') {
    console.log('Verified:', data.phone, 'via', data.channel)
    // mark user as verified in your database
  }

  res.sendStatus(200)
})

Retries

If your endpoint returns a non-2xx status or times out, SecureOTP will retry the delivery up to 3 times with exponential backoff (5s, 30s, 120s). If all retries fail, the event is dropped.

Security

Webhook payloads are sent over HTTPS. Always use an https:// URL for your webhook endpoint — plain HTTP endpoints are not supported in production.