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

# Webhook

> Webhook integration for notifying your system once a call or WhatsApp event is completed from our end.

Use webhooks to receive real-time notifications in your system whenever a call is completed or a WhatsApp message event occurs from our platform.

***

## Webhook Endpoint

You are required to provide us with a publicly accessible HTTPS endpoint (e.g., `https://yourdomain.com/webhook`). Our system will send a POST request to this endpoint with the event data.

## Request Method

All webhook notifications will be sent using the HTTP **POST** method with a JSON payload.

## Secret Token Authentication

To ensure that the webhook request is coming from an authorized source, a secret token will be included in the request headers. This helps verify that the payload originated from our system and not from a third-party source.

The secret token will be shared with you securely during setup and must be validated on your server for every webhook request.

**Header Example:**

```json theme={null}
{
  "Authorization": "Bearer YOUR_SECRET_TOKEN"
}
```

On your server, you should verify the token before processing the payload. If the token is invalid, respond with an HTTP `401 Unauthorized` status.

## Expected Response

Your endpoint should respond with an HTTP `200` status code upon successful receipt and processing of the data. If the response code is not `200`, our system may retry the webhook delivery.

***

## Sample Payloads

<Note>
  **Identifier**

  Depending on your campaign type, you will either get a `loan_id` (for Debt Collection) or a `lead_id` (for Lead Generation).
</Note>

<Tabs>
  <Tab title="Calls">
    ### Call Webhook Payload

    Call webhooks are triggered for the following events: **Contacted**, **No Contact**, **Failed**.

    When a call is completed, the following payload will be sent to your webhook endpoint:

    <Tabs>
      <Tab title="Debt Colletion">
        ```json theme={null}
        {
          "event": "call",
          "call_id": "aerfttYRDwcdtr",
          "agent_id": "aiyvytyTFrduav",
          "campaign_name": "Loan Recovery - Nov",
          "loan_id": "LN1029384",
          "name": "Rahul Sharma",
          "phone": "9999999999",
          "language": "hindi",
          "from_phone": "+918888888888",
          "status": "Contacted",
          "direction": "outbound",
          "duration": 45,
          "disposition": "Hangup",
          "summary": "The user cut the call mid conversation",
          "start_time": "2025-11-01T13:26:27",
          "end_time": "2025-11-01T13:27:12",
          "recording_id": "63c30c3d-ce24-4c33-a64a-c2f81ca48d0b",
          "transcript_id": "7ytf554-ce24-67sd-a64a-zdvuy74vjf74",
          "extracted_data": {
            "ptp_date": "2025-11-03"
          },
          "additional_data": {
            "custom_key": "value"
          }
        }
        ```

        ### Field Descriptions

        | Field             | Type    | Description                                               |
        | ----------------- | ------- | --------------------------------------------------------- |
        | `event`           | string  | Type of event (`call`)                                    |
        | `call_id`         | string  | Unique ID representing a call                             |
        | `agent_id`        | string  | Unique ID representing the agent                          |
        | `campaign_name`   | string  | Name of the campaign                                      |
        | `loan_id`         | string  | Unique loan ID for the customer                           |
        | `name`            | string  | Customer's full name                                      |
        | `phone`           | string  | Customer's phone number                                   |
        | `language`        | string  | Language used for conversation                            |
        | `from_phone`      | string  | Number used for dialing                                   |
        | `status`          | string  | Final call status (`Contacted` / `No Contact` / `Failed`) |
        | `direction`       | string  | Indicates call direction (`inbound` / `outbound`)         |
        | `duration`        | integer | Duration of call in seconds                               |
        | `disposition`     | string  | Call outcome                                              |
        | `summary`         | string  | Short summary of the call                                 |
        | `start_time`      | string  | Call start timestamp (ISO 8601 format)                    |
        | `end_time`        | string  | Call end timestamp (ISO 8601 format)                      |
        | `recording_id`    | string  | Unique ID representing the call recording                 |
        | `transcript_id`   | string  | Unique ID representing the call transcript                |
        | `extracted_data`  | object  | Additional data extracted from the call                   |
        | `additional_data` | object  | Custom fields specific to your business                   |
      </Tab>

      <Tab title="Lead Generation">
        ```json theme={null}
        {
          "event": "call",
          "call_id": "aerfttYRDwcdtr",
          "agent_id": "aiyvytyTFrduav",
          "campaign_name": "Sales Campaign",
          "lead_id": "LN1029384",
          "name": "Rahul Sharma",
          "phone": "9999999999",
          "language": "hindi",
          "from_phone": "+918888888888",
          "status": "Contacted",
          "direction": "outbound",
          "duration": 45,
          "disposition": "Hangup",
          "summary": "The user cut the call mid conversation",
          "start_time": "2025-11-01T13:26:27",
          "end_time": "2025-11-01T13:27:12",
          "recording_id": "63c30c3d-ce24-4c33-a64a-c2f81ca48d0b",
          "transcript_id": "7ytf554-ce24-67sd-a64a-zdvuy74vjf74",
          "extracted_data": {
            "ptp_date": "2025-11-03"
          },
          "additional_data": {
            "custom_key": "value"
          }
        }
        ```

        ### Field Descriptions

        | Field             | Type    | Description                                               |
        | ----------------- | ------- | --------------------------------------------------------- |
        | `event`           | string  | Type of event (`call`)                                    |
        | `call_id`         | string  | Unique ID representing a call                             |
        | `agent_id`        | string  | Unique ID representing the agent                          |
        | `campaign_name`   | string  | Name of the campaign                                      |
        | `lead_id`         | string  | Unique lead ID for the customer                           |
        | `name`            | string  | Customer's full name                                      |
        | `phone`           | string  | Customer's phone number                                   |
        | `language`        | string  | Language used for conversation                            |
        | `from_phone`      | string  | Number used for dialing                                   |
        | `status`          | string  | Final call status (`Contacted` / `No Contact` / `Failed`) |
        | `direction`       | string  | Indicates call direction (`inbound` / `outbound`)         |
        | `duration`        | integer | Duration of call in seconds                               |
        | `disposition`     | string  | Call outcome                                              |
        | `summary`         | string  | Short summary of the call                                 |
        | `start_time`      | string  | Call start timestamp (ISO 8601 format)                    |
        | `end_time`        | string  | Call end timestamp (ISO 8601 format)                      |
        | `recording_id`    | string  | Unique ID representing the call recording                 |
        | `transcript_id`   | string  | Unique ID representing the call transcript                |
        | `extracted_data`  | object  | Additional data extracted from the call                   |
        | `additional_data` | object  | Custom fields specific to your business                   |
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="WhatsApp">
    ### WhatsApp Webhook Events

    WhatsApp webhooks are triggered for the following message events: **Sent**, **Delivered**, **Read**, and **Failed**.

    <Accordion title="Message Sent">
      Triggered when a message is successfully sent to the WhatsApp server.

      ```json theme={null}
      {
        "event": "whatsapp",
        "message_id": "wamid.HBgLOTE5ODc2NTQzMjEVAgASGCA2QjNFQjA",
        "status: "sent",
        "conversation_id": "conv_abc123xyz",
        "campaign_name": "Payment Reminder - Nov",
        "loan_id": "LN1029384",
        "name": "Rahul Sharma",
        "phone": "919876543210",
        "message_type": "template",
        "template_name": "payment_reminder_v1",
        "timestamp": "2025-11-01T13:26:27",
        "additional_data": {
          "custom_key": "value"
        }
      }
      ```
    </Accordion>

    <Accordion title="Message Delivered">
      Triggered when the message is successfully delivered to the recipient's device.

      ```json theme={null}
      {
        "event": "whatsapp",
        "message_id": "wamid.HBgLOTE5ODc2NTQzMjEVAgASGCA2QjNFQjA",
        "status: "delivered",
        "conversation_id": "conv_abc123xyz",
        "campaign_name": "Payment Reminder - Nov",
        "loan_id": "LN1029384",
        "name": "Rahul Sharma",
        "phone": "919876543210",
        "message_type": "template",
        "template_name": "payment_reminder_v1",
        "timestamp": "2025-11-01T13:26:35",
        "additional_data": {
          "custom_key": "value"
        }
      }
      ```
    </Accordion>

    <Accordion title="Message Read">
      Triggered when the recipient reads the message (blue ticks).

      ```json theme={null}
      {
        "event": "whatsapp",
        "message_id": "wamid.HBgLOTE5ODc2NTQzMjEVAgASGCA2QjNFQjA",
        "status": "read",
        "conversation_id": "conv_abc123xyz",
        "campaign_name": "Payment Reminder - Nov",
        "loan_id": "LN1029384",
        "name": "Rahul Sharma",
        "phone": "919876543210",
        "message_type": "template",
        "template_name": "payment_reminder_v1",
        "timestamp": "2025-11-01T13:26:27",
        "additional_data": {
          "custom_key": "value"
        }
      }
      ```
    </Accordion>

    <Accordion title="Message Failed">
      Triggered when message delivery fails.

      ```json theme={null}
      {
        "event": "whatsapp",
        "message_id": "wamid.HBgLOTE5ODc2NTQzMjEVAgASGCA2QjNFQjA",
        "status": "failed",
        "conversation_id": "conv_abc123xyz",
        "campaign_name": "Payment Reminder - Nov",
        "loan_id": "LN1029384",
        "name": "Rahul Sharma",
        "phone": "919876543210",
        "message_type": "template",
        "template_name": "payment_reminder_v1",
        "timestamp": "2025-11-01T13:26:27",
        "error": [
          {
            "code": 131026,
            "title": "Message undeliverable",
            "message": "Recipient phone number not on WhatsApp"
          }
        ],
        "additional_data": {
          "custom_key": "value"
        }
      }
      ```
    </Accordion>

    <Note>
      **Identifier**

      Depending on your campaign type, you will either get a `loan_id` (for Debt Collection) or a `lead_id` (for Lead Generation).
    </Note>

    ### WhatsApp Field Descriptions

    <Tabs>
      <Tab title="Debt Colletion">
        | Field             | Type   | Description                                   |
        | ----------------- | ------ | --------------------------------------------- |
        | `event`           | string | Type of event (`whatsapp`)                    |
        | `message_id`      | string | Unique WhatsApp message ID                    |
        | `status`          | string | WhatsApp message Status                       |
        | `conversation_id` | string | Unique conversation thread ID                 |
        | `campaign_name`   | string | Name of the campaign                          |
        | `loan_id`         | string | Unique loan ID for the customer               |
        | `name`            | string | Customer's full name                          |
        | `phone`           | string | Customer's phone number                       |
        | `message_type`    | string | Type of message (`template`, `text`, `media`) |
        | `template_name`   | string | Name of the template used (if applicable)     |
        | `timestamp`       | string | Event timestamp (ISO 8601 format)             |
        | `error`           | array  | Error details (only for failed events)        |
        | `additional_data` | object | Custom fields specific to your business       |
      </Tab>

      <Tab title="Lead generation">
        | Field             | Type   | Description                                   |
        | ----------------- | ------ | --------------------------------------------- |
        | `event`           | string | Type of event (`whatsapp`)                    |
        | `message_id`      | string | Unique WhatsApp message ID                    |
        | `status`          | string | WhatsApp message Status                       |
        | `conversation_id` | string | Unique conversation thread ID                 |
        | `campaign_name`   | string | Name of the campaign                          |
        | `lead_id`         | string | Unique loan ID for the customer               |
        | `name`            | string | Customer's full name                          |
        | `phone`           | string | Customer's phone number                       |
        | `message_type`    | string | Type of message (`template`, `text`, `media`) |
        | `template_name`   | string | Name of the template used (if applicable)     |
        | `timestamp`       | string | Event timestamp (ISO 8601 format)             |
        | `error`           | array  | Error details (only for failed events)        |
        | `additional_data` | object | Custom fields specific to your business       |
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

***

## Retry Policy

If the webhook fails (non-200 response or timeout), we will retry up to **2 times** with exponential backoff.

## Security

<Warning>
  It is strongly recommended to verify the webhook source using the provided secret token. All webhook requests will be sent over HTTPS only.
</Warning>

For any questions or configuration changes, please contact our technical team.