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:

{
"status": "SENT",
"data": {
    "referenceId": "580884110b1b46668baa1d46a65f46d9",
    "timestamp": 1707743465000,
    "identity": "919899038845",
    "channel": "WHATSAPP"
}
}

This webhook is triggered when a user clicks the Approve button or the magic link on WhatsApp/SMS/Email during the authentication process.

Payload

The payload associated with this webhook provides the following information:

• token (string): Unique identifier for the request.
• timestamp (string): Date and time of the event in ISO 8601 format.
• mobile (object): Contains the user’s mobile number.
  • number (string): User’s phone number.
• requestId (string): Unique identifier for the authentication request.
• notificationType (string): Always “APPROVAL_ACTION” for this webhook.

Example Payload

{
  "token": "580884110b1b46668baa1d46a65f46d9",
  "timestamp": 1707743479000,
  "mobile": {
  "number": "919899038845"
  },
  "requestId": "580884110b1b46668baa1d46a65f46d9",
  "notificationType": "APPROVAL_ACTION"
}