> ## Documentation Index
> Fetch the complete documentation index at: https://docs.humanos.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# OTP Failed Event

> Fired when an OTP **SMS** could not be delivered: every eligible SMS provider was tried (synchronously or via carrier delivery reports) and none succeeded. Email OTP failures do not emit this event. Carrier delivery reports are asynchronous and occasionally corrected to "delivered" afterwards, so treat this event as *Humanos stopped retrying*, not as a guarantee the SMS never arrived. The safe reaction is to `PATCH` the `otp.resendEndpoint` URL exactly as delivered — a resend issues a fresh code and invalidates the old one, so it is harmless even if the original message did arrive late.

**Inbound webhook callback** — Humanos POSTs this payload to your registered webhook URL. This is not an endpoint you call; it is documented as a path so SDK code generators emit a typed payload model.



## OpenAPI

````yaml /versions/2026-07-06.yaml post /_webhooks/otp-failed
openapi: 3.1.0
info:
  title: Humanos API
  description: Humanos API
  version: '1.0'
  contact: {}
servers: []
security: []
tags:
  - name: humanosApp
    description: ''
paths:
  /_webhooks/otp-failed:
    post:
      tags:
        - Webhooks
      summary: OTP Failed Event
      description: >-
        Fired when an OTP **SMS** could not be delivered: every eligible SMS
        provider was tried (synchronously or via carrier delivery reports) and
        none succeeded. Email OTP failures do not emit this event. Carrier
        delivery reports are asynchronous and occasionally corrected to
        "delivered" afterwards, so treat this event as *Humanos stopped
        retrying*, not as a guarantee the SMS never arrived. The safe reaction
        is to `PATCH` the `otp.resendEndpoint` URL exactly as delivered — a
        resend issues a fresh code and invalidates the old one, so it is
        harmless even if the original message did arrive late.


        **Inbound webhook callback** — Humanos POSTs this payload to your
        registered webhook URL. This is not an endpoint you call; it is
        documented as a path so SDK code generators emit a typed payload model.
      operationId: webhooks_otp_failed
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OtpFailedEvent'
      responses:
        '200':
          description: Webhook received successfully
components:
  parameters:
    ApiVersion:
      name: API-Version
      in: header
      required: false
      schema:
        type: string
        pattern: ^\d{4}-\d{2}-\d{2}$
        example: '2026-07-06'
      description: >-
        Pin request, response, and webhook shapes to a specific dated API
        version (YYYY-MM-DD). Omit to use the version pinned to your API key
        (set when the key is created; new keys default to the latest version).
        New integrations should target the latest version.
  schemas:
    OtpFailedEvent:
      type: object
      properties:
        eventType:
          type: string
          enum:
            - otp.failed
        requestId:
          type: string
        internalId:
          type: string
        issuerDid:
          type: string
        user:
          type: object
          properties:
            contact:
              type: string
            id:
              type: string
            internalId:
              type: string
          required:
            - contact
            - id
          additionalProperties: false
        api_version:
          type: string
        otp:
          type: object
          properties:
            resendEndpoint:
              type: string
            error:
              title: OtpError
              type: object
              properties:
                code:
                  type: string
                message:
                  type: string
              required:
                - code
                - message
              additionalProperties: false
          required:
            - resendEndpoint
            - error
          additionalProperties: false
      required:
        - api_version
        - eventType
        - issuerDid
        - otp
        - requestId
        - user
      additionalProperties: false

````