Update a webhook subscription

Replaces a subscription. Takes the same body as create and every field is required, so send the full object, not only the fields you are changing.

PUT

https://app.touchsms.com.au/api/v2/webhook-subscriptions/{webhookSubscription}

Authorization

basicAuth
HTTP
required

Path parameters

webhookSubscription
integer
required
Webhook subscription ID.

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 touchSMS 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
}
include_sent_status
optional
boolean
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
optional
json
or
form
Required when request_method is POST.

Returns

200

The updated subscription.

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.
- include_sent_status
  optional
  boolean
  Whether a message_dlr subscription also receives sent receipts. Always false for other events.
- 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

403

The resource exists but does not belong to you, or you lack permission.

JSON

message
string
required

404

The resource does not exist.

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>

Update a webhook subscription

curl --request PUT \
  --url https://app.touchsms.com.au/api/v2/webhook-subscriptions/123 \
  --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.touchsms.com.au/api/v2/webhook-subscriptions/123';
const options = {
  method: 'PUT',
  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.touchsms.com.au/api/v2/webhook-subscriptions/123"

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.put(url, json=payload, headers=headers)

print(response.text)

Response example

{
  "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"
  }
}

{
  "message": "Unauthenticated."
}

{
  "message": "This action is unauthorized."
}

{
  "message": "Not Found"
}

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