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
}

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

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
}

Similar to WhatsApp, webhooks can be used to track the delivery status of SMS-based authentication requests.

Status Descriptions

The following statuses are delivered through webhooks for SMS authentication:

DELIVERED: Confirms that the message containing the authentication request has been successfully delivered to the recipient’s device.
FAILED: Signifies that the message delivery has encountered an issue.

Example Payloads

Here are JSON examples illustrating each status update for SMS delivery:

{
  "data": {
    "requestId": "unique_request_id",
    "authSessionId": "unique_auth_session_id",
    "traceId": "unique_trace_id",
    "status": "DELIVERED",
    "channel": "SMS",
    "identity": "identity_value",
    "metaData": {}
  },
  "eventType": "DLR",
  "timestamp": 1734513816000
}

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

Status Descriptions

The following statuses are delivered through webhooks for Viber authentication:

SENT: Indicates the message containing the authentication request has been sent to the recipient’s Viber 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 Viber 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 Viber 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 Viber delivery:

{
  "data": {
    "requestId": "unique_request_id",
    "authSessionId": "unique_auth_session_id",
    "traceId": "unique_trace_id",
    "status": "SENT",
    "channel": "VIBER",
    "identity": "identity_value",
    "metaData": {}
  },
  "eventType": "DLR",
  "timestamp": 1734513816000
}

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

Status Descriptions

The following statuses are delivered through webhooks for Email authentication:

SENT: Indicates the email containing the authentication request has been sent to the recipient’s email address.
DELIVERED: Confirms that the email has been successfully delivered to the recipient’s mailbox.
READ: Indicates the recipient has opened the email. (Note: This status is available only with specific email vendors that support read tracking.)
FAILED: Signifies that the email 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 email client and settings (e.g., email tracking 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 email client and settings.
The READ event works only with specific vendors that support read tracking.
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 Email delivery:

{
  "data": {
    "requestId": "unique_request_id",
    "authSessionId": "unique_auth_session_id",
    "traceId": "unique_trace_id",
    "status": "SENT",
    "channel": "EMAIL",
    "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
}

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
}

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

Example Payload

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

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

Example Payload

{
  "data": {
    "requestId": "unique_request_id",
    "authSessionId": "unique_auth_session_id",
    "traceId": "unique_trace_id",
    "status": "CLICKED",
    "channel": "VIBER",
    "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
}

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
}

The AUTH event is triggered upon successful authentication using an email address.

Example Payload

{
  "data": {
    
    "authSessionId": "unique_auth_session_id",
    "traceId": "unique_trace_id",
    "status": "INITIATED",
    "authenticationDetails": { 
      "email": {
        "requestId": "unique_request_id",
        "method": "OTP", //OTP or MAGIC_LINK
        "channel": [
          "EMAIL"
        ],
        "email": "USER_EMAIL"
      }
    }
  },
  "eventType": "AUTH",
  "timestamp": 1734518721
}

The AUTH event is triggered upon successful authentication using both a phone number and an email address.

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": {
        "requestId": "unique_request_id",
        "method": "OTP", //OTP or MAGIC_LINK
        "channel": [
          "EMAIL"
        ],
        "email": "USER_EMAIL"
      }
    }
  },
  "eventType": "AUTH",
  "timestamp": 1734530056
}

The AUTH event is triggered upon successful authentication using a social login.

Example Payload

{
  "data": {
    "authSessionId": "unique_auth_session_id",
    "traceId": "unique_trace_id",
    "status": "INITIATED",
    "authenticationDetails": {
      "email": {
        "requestId": "unique_request_id",
        "method": "OAUTH", 
        "channel": [
          "GOOGLE"
        ],
        "email": "USER_EMAIL"
      }
    }
  },
  "eventType": "AUTH",
  "timestamp": 1734617952
}

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
}

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
}

The AUTH event is triggered upon successful authentication using an email address.

Example Payload

{
  "data": {
    
    "authSessionId": "unique_auth_session_id",
    "traceId": "unique_trace_id",
    "token": "unique_token",
    "status": "SUCCESS",
    "authenticationDetails": { 
      "email": {
        "requestId": "unique_request_id",
        "method": "OTP", //OTP or MAGIC_LINK
        "channel": [
          "EMAIL"
        ],
        "email": "USER_EMAIL"
      }
    }
  },
  "eventType": "AUTH",
  "timestamp": 1734518721
}

The AUTH event is triggered upon successful authentication using both a phone number and an email address.

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": {
        "requestId": "unique_request_id",
        "method": "OTP", //OTP or MAGIC_LINK
        "channel": [
          "EMAIL"
        ],
        "email": "USER_EMAIL"
      }
    }
  },
  "eventType": "AUTH",
  "timestamp": 1734530056
}

The AUTH event is triggered upon successful authentication using a social login.

Example Payload

{
  "data": {
    "authSessionId": "unique_auth_session_id",
    "traceId": "unique_trace_id",
    "token": "unique_token",
    "status": "SUCCESS",
    "authenticationDetails": {
      "email": {
        "requestId": "unique_request_id",
        "method": "OAUTH", 
        "channel": [
          "GOOGLE"
        ],
        "email": "USER_EMAIL"
      }
    }
  },
  "eventType": "AUTH",
  "timestamp": 1734617952
}

​Types of Webhooks

Message Delivery Events

Auth Events

​Message Delivery Events

​Delivery Status Events

​Status Descriptions

​Sequence of Statuses

​Important Notes

​Example Payloads

​Status Descriptions

​Sequence of Statuses

​Important Notes

​Example Payloads

​Status Descriptions

​Example Payloads

​Status Descriptions

​Sequence of Statuses

​Important Notes

​Example Payloads

​Status Descriptions

​Sequence of Statuses

​Important Notes

​Example Payloads

​Clicked Status Events

​Example Payload

​Example Payload

​Example Payload

​Example Payload

​Auth Events

​Authentication Initiated Events

​Example Payload

​Example Payload

​Example Payload

​Example Payload

​Example Payload

​Fallback Events

​Example Payload

​Important Notes

​Authentication Completion Events

​Example Payload

​Example Payload

​Example Payload

​Example Payload

​Example Payload

Types of Webhooks

Message Delivery Events

Delivery Status Events

Status Descriptions

Sequence of Statuses

Important Notes

Example Payloads

Status Descriptions

Sequence of Statuses

Important Notes

Example Payloads

Status Descriptions

Example Payloads

Status Descriptions

Sequence of Statuses

Important Notes

Example Payloads

Status Descriptions

Sequence of Statuses

Important Notes

Example Payloads

Clicked Status Events

Example Payload

Example Payload

Example Payload

Example Payload

Auth Events

Authentication Initiated Events

Example Payload

Example Payload

Example Payload

Example Payload

Example Payload

Fallback Events

Example Payload

Important Notes

Authentication Completion Events

Example Payload

Example Payload

Example Payload

Example Payload

Example Payload