OTP Failed Event

Webhook triggered when OTP (One-Time Password) delivery fails

Overview

The otp.failed event is triggered when an OTP delivery attempt fails. This event always has rejected: true and includes error details along with a resend endpoint for retrying the OTP delivery.

Example Payload

{
  "eventType": "otp.failed",
  "issuerId": "680a65a4da4a16c0ea64face",
  "requestId": "68c6b2c3d4e5f6789012345",
  "subjectId": "68c6b2c3d4e5f6789012346",
  "subjectInternalId": "user_otp_001",
  "rejected": true,
  "decisionDate": "2024-01-15T22:45:00.000Z",
  "metadata": {
    "contact": "[phone]",
    "errorCode": "INVALID_PHONE_NUMBER",
    "errorMessage": "The phone number format is invalid for the selected country",
    "resendEndpoint": "/v0/request/resend/507f1f77bcf86cd799439011"
  }
}

Base Fields

All OTP failed events include these common fields:

Field	Type	Required	Description
eventType	string	Yes	Always "otp.failed"
issuerId	string	Yes	Organization/issuer identifier
requestId	string	Yes	Request identifier
subjectId	string	Yes	Subject (user) identifier
subjectInternalId	string	No	Internal subject identifier
rejected	boolean	Yes	Always true for OTP failed events
decisionDate	Date	Yes	Timestamp when the OTP failure was recorded

OTP Failure Metadata

The metadata field is required and contains OTP failure details:

Field	Type	Required	Description
contact	string	Yes	Contact information (phone number or email)
errorCode	string	Yes	Specific error code indicating the failure reason
errorMessage	string	Yes	Human-readable error message
resendEndpoint	string	Yes	API endpoint to resend the OTP

Handling OTP Failures

When you receive an otp.failed event:

1. Log the error - Record the errorCode and errorMessage for debugging
2. Notify the user - Inform the user about the delivery failure
3. Retry if needed - Use the resendEndpoint to attempt OTP delivery again

The resendEndpoint provides a direct API path to retry the OTP delivery without requiring the original request details.