Create a webhook subscription

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

POST

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

Authorization

basicAuth
HTTP
required

Request body JSON required

name
string
required
Shown in the web app.
event
message_received
or
message_dlr
or
optout_created
or
message_received_3cx
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.
url
string
required
Where to send the webhook. Cannot point at a MessagePort domain.

format: uri
request_method
POST
or
GET
required
headers
array of
object
required
Custom headers sent with each webhook. Required; send [] for none.
- key
  string
  required
  A valid HTTP header name.
  
  maxLength: 50 · minLength: 3
- value
  string
  required
  maxLength: 200 · minLength: 3
}
request_encoding_type
optional
json
or
form
Required when request_method is POST.

Returns

201

Subscription created.

JSON

data
optional
object
- id
  optional
  integer
- status
  optional
  Active
  or
  Disabled
  or
  Disabled Failing
  Disabled Failing means the subscription was disabled automatically after repeated delivery failures and receives no events until re-enabled.
- event
  optional
  message_received
  or
  message_dlr
  or
  optout_created
  or
  message_received_3cx
  
  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.
- name
  optional
  string
- url
  optional
  string
  format: uri
- request_method
  optional
  POST
  or
  GET
- request_encoding_type
  optional
  json
  or
  form
  or
  null
- headers
  optional
  array of
  object
  key
  string
  required
  A valid HTTP header name.
  
  maxLength: 50 · minLength: 3
  value
  string
  required
  maxLength: 200 · minLength: 3
- created_at
  optional
  string
  format: date-time
- updated_at
  optional
  string
  format: date-time
}

401

Missing, malformed or invalid API credentials.

JSON

message
string
required

422

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

JSON

message
optional
string
errors
optional
map of
array<string>

Create a webhook subscription

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"
    }
  ]
}
'

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));

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)

Response example

{
  "data": {
    "id": 123,
    "status": "Active",
    "event": "message_received",
    "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"
  }
}

{
  "message": "Unauthenticated."
}

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