​
Types of Webhooks

The OTPLESS system offers various webhooks to cater to different needs:

Message Delivery Events

Trigger an event whenever there is a change in the delivery status of a message sent via WhatsApp, SMS, Viber or Email.

Auth Events

Trigger when there is any auth specific events.

​
Message Delivery Events

​
Delivery Status Events

Webhooks can be leveraged to track the delivery status of authentication requests initiated via WhatsApp.

​
Status Descriptions

The following statuses are delivered through webhooks for WhatsApp authentication:
  • SENT: Indicates the message containing the authentication request has been sent to the recipient’s WhatsApp number.
  • DELIVERED: Confirms that the message has been successfully delivered to the recipient’s device.
  • READ: Indicates the recipient has read the message.
  • FAILED: Signifies that the message delivery has encountered an issue.

​
Sequence of Statuses

Ideally, the sequence of status updates follows the order: SENT -> DELIVERED -> READ. However, variations might occur depending on the recipient’s WhatsApp settings (e.g., read receipts disabled). If a later status is received, it implies all preceding statuses have been fulfilled.

​
Important Notes

  • Webhooks for delivery status updates are not mandatory.
  • The availability of status updates depends on the recipient’s WhatsApp settings.
  • There might be instances where webhooks are missed due to technical issues on either side (client or server). The system implements retries to mitigate this.

​
Example Payloads

Here are JSON examples illustrating each status update for WhatsApp delivery:
{
  "data": {
    "requestId": "unique_request_id",
    "authSessionId": "unique_auth_session_id",
    "traceId": "unique_trace_id",
    "status": "SENT",
    "channel": "WHATSAPP",
    "identity": "identity_value",
    "metaData": {}
  },
  "eventType": "DLR",
  "timestamp": 1734513816000
}

​
Clicked Status Events

The CLICKED event for WhatsApp indicates that the recipient has clicked on the authentication link sent via WhatsApp.

​
Example Payload

{
  "data": {
    "requestId": "unique_request_id",
    "authSessionId": "unique_auth_session_id",
    "traceId": "unique_trace_id",
    "status": "CLICKED",
    "channel": "WHATSAPP",
    "identity": "identity_value",
    "metaData": {}
  },
  "eventType": "DLR",
  "timestamp": 1734615829169
}

​
Auth Events

In addition to authentication, OTPLESS offers webhooks for specific auth events for fallback(in case of Smart Auth) and on authentication completion:

​
Authentication Initiated Events

The AUTH event is triggered upon successful authentication using a phone number.

​
Example Payload

{
  "data": {
    
    "authSessionId": "unique_auth_session_id",
    "traceId": "unique_trace_id",
    "status": "INITIATED",
    "authenticationDetails": {
      "phone": {
        "requestId": "unique_request_id",
        "method": "OTP", //OTP or SILENT_AUTH
        "channel": [
          "WHATSAPP/SMS/VIBER"
        ],
        "phoneNumber": "USER_NUMBER",
        "countryCode": "COUNTRY_CODE"
      },
      "email": {}
    }
  },
  "eventType": "AUTH",
  "timestamp": 1734513827
}

​
Fallback Events

The AUTH event is triggered when a fallback occurs from one channel to another.

​
Example Payload

{
  "data": {
    "requestId": "unique_request_id",
    "authSessionId": "unique_auth_session_id",
    "traceId": "unique_trace_id",
    "status": "FALLBACK",
    "fromChannel": "WHATSAPP", //WHATSAPP, SMS, SILENT_AUTH, VIBER
    "toChannel": "SMS" //WHATSAPP, SMS, VIBER
  },
  "eventType": "AUTH",
  "timestamp": 1734516528720
}

​
Important Notes

  • Possible channels could be WHATSAPP, SMS, VIBER, SILENT_AUTH

​
Authentication Completion Events

The AUTH event is triggered upon successful authentication using a phone number.

​
Example Payload

{
  "data": {
    
    "authSessionId": "unique_auth_session_id",
    "traceId": "unique_trace_id",
    "token": "unique_token",
    "status": "SUCCESS",
    "authenticationDetails": {
      "phone": {
        "requestId": "unique_request_id",
        "method": "OTP", //OTP or SILENT_AUTH
        "channel": [
          "WHATSAPP/SMS/VIBER"
        ],
        "phoneNumber": "USER_NUMBER",
        "countryCode": "COUNTRY_CODE"
      },
      "email": {}
    }
  },
  "eventType": "AUTH",
  "timestamp": 1734513827
}