---
title: "Create a webhook subscription"
description: "Subscribes a URL to an event. `headers` is required even if empty (send `[]`).\n`request_encoding_type` is required when `request_method` is `POST`.\n"
version: "v2"
---

> Documentation Index
> Fetch the complete documentation index at: https://dev.messageport.com.au/llms.txt
> Use this file to discover all available pages before exploring further.

Path: MessagePort API › Webhook subscriptions

`POST /v2/webhook-subscriptions`

Subscribes a URL to an event. `headers` is required even if empty (send `[]`).
`request_encoding_type` is required when `request_method` is `POST`.

## Authentication

- `basicAuth`, http, header `Authorization`

## Request body

_Required._

- `name` (`createWebhookSubscription.name`; string, required) — Shown in the web app.
- `event` (`createWebhookSubscription.event`; string, required) — - `message_received`: an inbound message was received. - `message_dlr`: a delivery receipt was received for an outbound message. - `optout_created`: a number opted out. - `message_received_3cx`: an inbound message, formatted for 3CX.
  - one of `"message_received"`, `"message_dlr"`, `"optout_created"`, `"message_received_3cx"`
- `url` (`createWebhookSubscription.url`; string, required) — Where to send the webhook. Cannot point at a MessagePort domain.
  - format `uri`
- `request_method` (`createWebhookSubscription.request_method`; string, required)
  - one of `"POST"`, `"GET"`
- `headers` (`createWebhookSubscription.headers`; array<object>, required) — Custom headers sent with each webhook. Required; send `[]` for none.
  - `key` (`createWebhookSubscription.headers.key`; string, required) — A valid HTTP header name.
    - minLength 3; maxLength 50
  - `value` (`createWebhookSubscription.headers.value`; string, required)
    - minLength 3; maxLength 200
- `include_sent_status` (`createWebhookSubscription.include_sent_status`; boolean, optional) — `message_dlr` only. Also send a `sent` receipt when each message is handed to the carrier, before the final status. Ignored (stored as `false`) for other events. Left out on update, the current value is kept.
  - default `false`
- `request_encoding_type` (`createWebhookSubscription.request_encoding_type`; string, optional) — Required when `request_method` is `POST`.
  - one of `"json"`, `"form"`

## Example request

```json
{
  "name": "Inbound to CRM",
  "event": "message_received",
  "url": "https://example.com/hooks/inbound",
  "request_method": "POST",
  "request_encoding_type": "json",
  "headers": [
    {
      "key": "X-Api-Key",
      "value": "abc123"
    }
  ]
}
```

## Code samples

### cURL

```bash
curl --request POST \
  --url https://app.messageport.com.au/api/v2/webhook-subscriptions \
  --header 'Authorization: Basic <credentials>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Inbound to CRM",
  "event": "message_received",
  "url": "https://example.com/hooks/inbound",
  "request_method": "POST",
  "request_encoding_type": "json",
  "headers": [
    {
      "key": "X-Api-Key",
      "value": "abc123"
    }
  ]
}
'
```

### TypeScript

```typescript
const url = 'https://app.messageport.com.au/api/v2/webhook-subscriptions';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json', Authorization: 'Basic <credentials>'},
  body: JSON.stringify({
    name: 'Inbound to CRM',
    event: 'message_received',
    url: 'https://example.com/hooks/inbound',
    request_method: 'POST',
    request_encoding_type: 'json',
    headers: [{key: 'X-Api-Key', value: 'abc123'}]
  })
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));
```

### Python

```python
import requests

url = "https://app.messageport.com.au/api/v2/webhook-subscriptions"

payload = {
    "name": "Inbound to CRM",
    "event": "message_received",
    "url": "https://example.com/hooks/inbound",
    "request_method": "POST",
    "request_encoding_type": "json",
    "headers": [
        {
            "key": "X-Api-Key",
            "value": "abc123"
        }
    ]
}
headers = {
    "Content-Type": "application/json",
    "Authorization": "Basic <credentials>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
```

## Responses

### 201

Subscription created.

#### Example

```json
{
  "data": {
    "id": 123,
    "status": "Active",
    "event": "message_received",
    "include_sent_status": false,
    "name": "Inbound to CRM",
    "url": "https://example.com/hooks/inbound",
    "request_method": "POST",
    "request_encoding_type": "json",
    "headers": [
      {
        "key": "X-Api-Key",
        "value": "abc123"
      }
    ],
    "created_at": "2024-02-02T23:51:19Z",
    "updated_at": "2024-03-11T02:14:07Z"
  }
}
```

- `data` (`createWebhookSubscription.response.201.data`; object, optional)
  - example `{"id":123,"status":"Active","event":"message_received","include_sent_status":false,"name":"Inbound to CRM","url":"https://example.com/hooks/inbound","request_method":"POST","request_encoding_type":"json","headers":[{"key":"X-Api-Key","value":"abc123"}],"created_at":"2024-02-02T23:51:19Z","updated_at":"2024-03-11T02:14:07Z"}`
  - `id` (`createWebhookSubscription.response.201.data.id`; integer, optional)
  - `status` (`createWebhookSubscription.response.201.data.status`; string, optional) — `Disabled Failing` means the subscription was disabled automatically after repeated delivery failures and receives no events until re-enabled.
    - one of `"Active"`, `"Disabled"`, `"Disabled Failing"`
  - `event` (`createWebhookSubscription.response.201.data.event`; string, optional) — - `message_received`: an inbound message was received. - `message_dlr`: a delivery receipt was received for an outbound message. - `optout_created`: a number opted out. - `message_received_3cx`: an inbound message, formatted for 3CX.
    - one of `"message_received"`, `"message_dlr"`, `"optout_created"`, `"message_received_3cx"`
  - `include_sent_status` (`createWebhookSubscription.response.201.data.include_sent_status`; boolean, optional) — Whether a `message_dlr` subscription also receives `sent` receipts. Always `false` for other events.
  - `name` (`createWebhookSubscription.response.201.data.name`; string, optional)
  - `url` (`createWebhookSubscription.response.201.data.url`; string, optional)
    - format `uri`
  - `request_method` (`createWebhookSubscription.response.201.data.request_method`; string, optional)
    - one of `"POST"`, `"GET"`
  - `request_encoding_type` (`createWebhookSubscription.response.201.data.request_encoding_type`; string | null, optional)
    - one of `"json"`, `"form"`, `null`
  - `headers` (`createWebhookSubscription.response.201.data.headers`; array<object>, optional)
    - `key` (`createWebhookSubscription.response.201.data.headers.key`; string, required) — A valid HTTP header name.
      - minLength 3; maxLength 50
    - `value` (`createWebhookSubscription.response.201.data.headers.value`; string, required)
      - minLength 3; maxLength 200
  - `created_at` (`createWebhookSubscription.response.201.data.created_at`; string, optional)
    - format `date-time`
  - `updated_at` (`createWebhookSubscription.response.201.data.updated_at`; string, optional)
    - format `date-time`

### 401

Missing, malformed or invalid API credentials.

#### Example

```json
{
  "message": "Unauthenticated."
}
```

- `message` (`createWebhookSubscription.response.401.message`; string, required)

### 422

The request failed validation. `errors` lists the messages for each invalid field.

#### Example

```json
{
  "message": "The messages field is required.",
  "errors": {
    "messages": [
      "The messages field is required."
    ]
  }
}
```

- `message` (`createWebhookSubscription.response.422.message`; string, optional)
- `errors` (`createWebhookSubscription.response.422.errors`; map<array<string>>, optional)


Source: https://dev.messageport.com.au/api/webhook-subscriptions/create/index.md