# Survey Webhooks

When a survey completes, a POST request is sent to your webhook URL with the survey results.

## Webhook Payload

```json
{
  "survey_id": 456,
  "metadata": { "campaign_id": "summer2025", "customer_segment": "premium" },
  "results": [
    {
      "phone_number": "019XXXXXXXX",
      "status": "answered",
      "duration": 45,
      "response": "1",
      "responses": ["1", "5"]
    },
    {
      "phone_number": "018XXXXXXXX",
      "status": "answered",
      "duration": 62,
      "response": "2",
      "responses": ["2", "4", "1"]
    },
    {
      "phone_number": "017XXXXXXXX",
      "status": "not_answered",
      "duration": 0
    }
  ]
}
```

### Payload Fields

| Field | Type | Description |
| --- | --- | --- |
| survey_id | integer | The unique identifier of the survey |
| metadata | object | Custom metadata passed when creating the survey (optional) |
| results | array | Array of result objects for each phone number |

### Result Object Fields

| Field | Type | Description |
| --- | --- | --- |
| phone_number | string | The phone number of the respondent |
| status | string | Call status: `pending`, `answered`, `not_answered`, or `failed` |
| duration | integer | Call duration in seconds (0 if not answered) |
| response | string | The first key pressed by the respondent (only if status is `answered`) |
| responses | array | All keys pressed during the survey (only if status is `answered`) |

:::note
The webhook is sent once when the survey status becomes "completed". The `response` and `responses` fields are only present when the call status is `answered`.
:::