On this page

Per-Service Webhook Resource

The Per-Service Webhook resource allows you to control the effects of webhooks in a particular Conversation Service. The webhooks will only fire for activity at the service-level.

Services allow you to:

Create multiple, distinct environments (such as dev, stage, and prod) under a single Twilio account
Scope access to resources through both the REST and client APIs
Configure different service instances with specific behaviors

Every service can have unique webhook targets. This means you can include different metadata in the URLs or even trigger different behavior for different services.

Webhook targets for the Service Instance (the URL that Twilio will invoke) are configured in the Twilio Console.

If configured, service-scoped webhooks will override your global webhook settings such that only the service-scoped hooks will fire. This applies only to the services where service-level hooks are configured. See Conversations Webhooksfor more information.

ServiceWebhookConfiguration Properties

Property nameTypePIIDescription

account_sidSID<AC>

Not PII

The unique ID of the Account responsible for this service.

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34

chat_service_sidSID<IS>

Not PII

The unique ID of the Conversation Service this conversation belongs to.

Pattern: ^IS[0-9a-fA-F]{32}$Min length: 34Max length: 34

pre_webhook_urlstring<uri>

Not PII

The absolute url the pre-event webhook request should be sent to.

post_webhook_urlstring<uri>

Not PII

The absolute url the post-event webhook request should be sent to.

filtersarray[string]

Not PII

The list of events that your configured webhook targets will receive. Events not configured here will not fire. Possible values are onParticipantAdd, onParticipantAdded, onDeliveryUpdated, onConversationUpdated, onConversationRemove, onParticipantRemove, onConversationUpdate, onMessageAdd, onMessageRemoved, onParticipantUpdated, onConversationAdded, onMessageAdded, onConversationAdd, onConversationRemoved, onParticipantUpdate, onMessageRemove, onMessageUpdated, onParticipantRemoved, onMessageUpdate or onConversationStateUpdated.

methodenum<string>

Not PII

The HTTP method to be used when sending a webhook request. One of GET or POST.

Possible values:

GETPOST

urlstring<uri>

Not PII

An absolute API resource URL for this webhook.

Fetch a ServiceWebhookConfiguration resource

GET https://conversations.twilio.com/v1/Services/{ChatServiceSid}/Configuration/Webhooks

Path parameters

Property nameTypeRequiredPIIDescription

ChatServiceSidSID<IS>required

Not PII

The unique ID of the Conversation Service this conversation belongs to.

Pattern: ^IS[0-9a-fA-F]{32}$Min length: 34Max length: 34

Fetch a Service Webhook

Node.js

Python

Java

PHP

Ruby

twilio-cli

curl


_19// Download the helper library from https://www.twilio.com/docs/node/install
_19const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_19
_19// Find your Account SID and Auth Token at twilio.com/console
_19// and set the environment variables. See http://twil.io/secure
_19const accountSid = process.env.TWILIO_ACCOUNT_SID;
_19const authToken = process.env.TWILIO_AUTH_TOKEN;
_19const client = twilio(accountSid, authToken);
_19
_19async function fetchServiceWebhookConfiguration() {
_19  const webhook = await client.conversations.v1
_19    .services("ISXXXXXXXXXXXXXXXXXXXXXX")
_19    .configuration.webhooks()
_19    .fetch();
_19
_19  console.log(webhook.accountSid);
_19}
_19
_19fetchServiceWebhookConfiguration();

Output


_12{
_12  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_12  "chat_service_sid": "ISXXXXXXXXXXXXXXXXXXXXXX",
_12  "pre_webhook_url": "https://www.example.com/pre",
_12  "post_webhook_url": "https://www.example.com/post",
_12  "filters": [
_12    "onMessageRemove",
_12    "onParticipantAdd"
_12  ],
_12  "method": "POST",
_12  "url": "https://conversations.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Configuration/Webhooks"
_12}

Update a ServiceWebhookConfiguration resource

POST https://conversations.twilio.com/v1/Services/{ChatServiceSid}/Configuration/Webhooks

Path parameters

Property nameTypeRequiredPIIDescription

ChatServiceSidSID<IS>required

Not PII

The unique ID of the Conversation Service this conversation belongs to.

Pattern: ^IS[0-9a-fA-F]{32}$Min length: 34Max length: 34

Request body parameters

Property nameTypeRequiredPIIDescription

PreWebhookUrlstring<uri>Optional

Not PII

The absolute url the pre-event webhook request should be sent to.

PostWebhookUrlstring<uri>Optional

Not PII

The absolute url the post-event webhook request should be sent to.

Filtersarray[string]Optional

Not PII

MethodstringOptional

Not PII

The HTTP method to be used when sending a webhook request. One of GET or POST.

Update a Service Webhook

Node.js

Python

Java

PHP

Ruby

twilio-cli

curl


_24// Download the helper library from https://www.twilio.com/docs/node/install
_24const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_24
_24// Find your Account SID and Auth Token at twilio.com/console
_24// and set the environment variables. See http://twil.io/secure
_24const accountSid = process.env.TWILIO_ACCOUNT_SID;
_24const authToken = process.env.TWILIO_AUTH_TOKEN;
_24const client = twilio(accountSid, authToken);
_24
_24async function updateServiceWebhookConfiguration() {
_24  const webhook = await client.conversations.v1
_24    .services("ISXXXXXXXXXXXXXXXXXXXXXX")
_24    .configuration.webhooks()
_24    .update({
_24      filters: ["onConversationUpdated", "onMessageRemoved"],
_24      method: "POST",
_24      postWebhookUrl: "https://company.com/archive-every-action",
_24      preWebhookUrl: "https://company.com/filtering-and-permissions",
_24    });
_24
_24  console.log(webhook.accountSid);
_24}
_24
_24updateServiceWebhookConfiguration();

Output


_12{
_12  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_12  "chat_service_sid": "ISXXXXXXXXXXXXXXXXXXXXXX",
_12  "pre_webhook_url": "https://company.com/filtering-and-permissions",
_12  "post_webhook_url": "https://company.com/archive-every-action",
_12  "filters": [
_12    "onMessageRemoved",
_12    "onParticipantAdded"
_12  ],
_12  "method": "POST",
_12  "url": "https://conversations.twilio.com/v1/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Configuration/Webhooks"
_12}