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

Resource properties

account_sidtype: SID<AC>Not PII

The unique ID of the Account responsible for this service.

chat_service_sidtype: SID<IS>Not PII

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

pre_webhook_urltype: string<URI>Not PII

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

post_webhook_urltype: string<URI>Not PII

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

filterstype: 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.

methodtype: enum<STRING>Not PII

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

Possible values:

GETPOST

urltype: string<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

Parameters

URI parameters

ChatServiceSidtype: SID<IS>Not PII

Path Parameter

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

Fetch a Service Webhook

Node.js

Python

Java

PHP

Ruby

twilio-cli

curl


_12// Download the helper library from https://www.twilio.com/docs/node/install
_12// Find your Account SID and Auth Token at twilio.com/console
_12// and set the environment variables. See http://twil.io/secure
_12const accountSid = process.env.TWILIO_ACCOUNT_SID;
_12const authToken = process.env.TWILIO_AUTH_TOKEN;
_12const client = require('twilio')(accountSid, authToken);
_12
_12client.conversations.v1.services('ISXXXXXXXXXXXXXXXXXXXXXX')
_12                       .configuration
_12                       .webhooks()
_12                       .fetch()
_12                       .then(webhook => console.log(webhook.chatServiceSid));

Output


_12{
_12  "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_12  "chat_service_sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_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/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Configuration/Webhooks"
_12}

Update a ServiceWebhookConfiguration resource

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

Parameters

URI parameters

ChatServiceSidtype: SID<IS>Not PII

Path Parameter

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

Request body parameters

PreWebhookUrltype: string<URI>Not PII

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

PostWebhookUrltype: string<URI>Not PII

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

Filterstype: string[]Not PII

Methodtype: stringNot 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


_17// Download the helper library from https://www.twilio.com/docs/node/install
_17// Find your Account SID and Auth Token at twilio.com/console
_17// and set the environment variables. See http://twil.io/secure
_17const accountSid = process.env.TWILIO_ACCOUNT_SID;
_17const authToken = process.env.TWILIO_AUTH_TOKEN;
_17const client = require('twilio')(accountSid, authToken);
_17
_17client.conversations.v1.services('ISXXXXXXXXXXXXXXXXXXXXXX')
_17      .configuration
_17      .webhooks()
_17      .update({
_17         filters: ['onConversationUpdated', 'onMessageRemoved'],
_17         method: 'POST',
_17         postWebhookUrl: 'https://company.com/archive-every-action',
_17         preWebhookUrl: 'https://company.com/filtering-and-permissions'
_17       })
_17      .then(webhook => console.log(webhook.chatServiceSid));

Output


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