Download OpenAPI specification:Download

Webhooks

List webhooks

List all webhooks for a given app as specified by the App ID.

Request
Security:
Basic
or
oAuth2
path Parameters
project_id
required
string

The unique ID of the project. You can find this on the Sinch Dashboard.

app_id
required
string

The unique ID of the app. You can find this on the Sinch Dashboard.

Responses
200

A successful response.

Response Schema: application/json
Array of objects (Webhook)

List of webhooks belonging to a specific project ID and app ID

Array
app_id
required
string

The app that this webhook belongs to.

target
required
string

The target url where events should be sent to. Maximum URL length is 742. The conversation-api.*.sinch.com subdomains are forbidden.

triggers
required
Array of strings (WebhookTrigger)

An array of triggers that should trigger the webhook and result in an event being sent to the target url. Refer to the list of Webhook Triggers for a complete list.

Items Enum: "UNSPECIFIED_TRIGGER" "MESSAGE_DELIVERY" "EVENT_DELIVERY" "MESSAGE_INBOUND" "EVENT_INBOUND" "CONVERSATION_START" "CONVERSATION_STOP" "CONTACT_CREATE" "CONTACT_DELETE" "CONTACT_MERGE" "CONTACT_UPDATE" "UNSUPPORTED" "OPT_IN" "OPT_OUT" "CAPABILITY" "CONVERSATION_DELETE"
object (ClientCredentials)
id
string

The ID of the webhook.

secret
string

Optional secret be used to sign contents of webhooks sent by the Conversation API. You can then use the secret to verify the signature.

target_type
string (WebhookTargetType)
Enum: "DISMISS" "GRPC" "HTTP"
400

Malformed request

401

Incorrect credentials

403

Correct credentials but you don't have access to the requested resource

500

Correct credentials but you don't have access to the requested resource

501

Something went wrong on our end, try again with exponential back-off

get/v1/projects/{project_id}/apps/{app_id}/webhooks
Request samples
import fetch from 'node-fetch';

async function run() {
  const projectId = 'YOUR_project_id_PARAMETER';
  const appId = 'YOUR_app_id_PARAMETER';
  const resp = await fetch(
    `https://eu.conversation.api.sinch.com/v1/projects/${projectId}/apps/${appId}/webhooks`,
    {
      method: 'GET',
      headers: {
        Authorization: 'Basic ' + Buffer.from('<username>:<password>').toString('base64')
      }
    }
  );

  const data = await resp.text();
  console.log(data);
}

run();
Response samples
application/json
{
  • "webhooks": [
    • {
      }
    ]
}

Create a new webhook

Creates a webhook for receiving callbacks on specific triggers. You can create up to 5 webhooks per app.

Request
Security:
Basic
or
oAuth2
path Parameters
project_id
required
string

The unique ID of the project. You can find this on the Sinch Dashboard.

Request Body schema: application/json

Required. The Webhook to create

app_id
required
string

The app that this webhook belongs to.

target
required
string

The target url where events should be sent to. Maximum URL length is 742. The conversation-api.*.sinch.com subdomains are forbidden.

triggers
required
Array of strings (WebhookTrigger)

An array of triggers that should trigger the webhook and result in an event being sent to the target url. Refer to the list of Webhook Triggers for a complete list.

Items Enum: "UNSPECIFIED_TRIGGER" "MESSAGE_DELIVERY" "EVENT_DELIVERY" "MESSAGE_INBOUND" "EVENT_INBOUND" "CONVERSATION_START" "CONVERSATION_STOP" "CONTACT_CREATE" "CONTACT_DELETE" "CONTACT_MERGE" "CONTACT_UPDATE" "UNSUPPORTED" "OPT_IN" "OPT_OUT" "CAPABILITY" "CONVERSATION_DELETE"
object (ClientCredentials)
secret
string

Optional secret be used to sign contents of webhooks sent by the Conversation API. You can then use the secret to verify the signature.

target_type
string (WebhookTargetType)
Enum: "DISMISS" "GRPC" "HTTP"
Responses
200

A successful response.

Response Schema: application/json
app_id
required
string

The app that this webhook belongs to.

target
required
string

The target url where events should be sent to. Maximum URL length is 742. The conversation-api.*.sinch.com subdomains are forbidden.

triggers
required
Array of strings (WebhookTrigger)

An array of triggers that should trigger the webhook and result in an event being sent to the target url. Refer to the list of Webhook Triggers for a complete list.

Items Enum: "UNSPECIFIED_TRIGGER" "MESSAGE_DELIVERY" "EVENT_DELIVERY" "MESSAGE_INBOUND" "EVENT_INBOUND" "CONVERSATION_START" "CONVERSATION_STOP" "CONTACT_CREATE" "CONTACT_DELETE" "CONTACT_MERGE" "CONTACT_UPDATE" "UNSUPPORTED" "OPT_IN" "OPT_OUT" "CAPABILITY" "CONVERSATION_DELETE"
object (ClientCredentials)
id
string

The ID of the webhook.

secret
string

Optional secret be used to sign contents of webhooks sent by the Conversation API. You can then use the secret to verify the signature.

target_type
string (WebhookTargetType)
Enum: "DISMISS" "GRPC" "HTTP"
400

Malformed request

401

Incorrect credentials

403

Correct credentials but you don't have access to the requested resource

500

Correct credentials but you don't have access to the requested resource

501

Something went wrong on our end, try again with exponential back-off

post/v1/projects/{project_id}/webhooks
Request samples
application/json
{
  • "app_id": "string",
  • "target": "string",
  • "triggers": [
    • "MESSAGE_DELIVERY"
    ]
}
Response samples
application/json
{
  • "app_id": "string",
  • "client_credentials": {
    • "client_id": "string",
    • "client_secret": "string",
    • "endpoint": "string"
    },
  • "id": "string",
  • "secret": "string",
  • "target": "string",
  • "target_type": "DISMISS",
  • "triggers": [
    • "MESSAGE_DELIVERY"
    ]
}

Get a webhook

Get a webhook as specified by the webhook ID.

Request
Security:
Basic
or
oAuth2
path Parameters
project_id
required
string

The unique ID of the project. You can find this on the Sinch Dashboard.

webhook_id
required
string

The unique ID of the webhook.

Responses
200

A successful response.

Response Schema: application/json
app_id
required
string

The app that this webhook belongs to.

target
required
string

The target url where events should be sent to. Maximum URL length is 742. The conversation-api.*.sinch.com subdomains are forbidden.

triggers
required
Array of strings (WebhookTrigger)

An array of triggers that should trigger the webhook and result in an event being sent to the target url. Refer to the list of Webhook Triggers for a complete list.

Items Enum: "UNSPECIFIED_TRIGGER" "MESSAGE_DELIVERY" "EVENT_DELIVERY" "MESSAGE_INBOUND" "EVENT_INBOUND" "CONVERSATION_START" "CONVERSATION_STOP" "CONTACT_CREATE" "CONTACT_DELETE" "CONTACT_MERGE" "CONTACT_UPDATE" "UNSUPPORTED" "OPT_IN" "OPT_OUT" "CAPABILITY" "CONVERSATION_DELETE"
object (ClientCredentials)
id
string

The ID of the webhook.

secret
string

Optional secret be used to sign contents of webhooks sent by the Conversation API. You can then use the secret to verify the signature.

target_type
string (WebhookTargetType)
Enum: "DISMISS" "GRPC" "HTTP"
400

Malformed request

401

Incorrect credentials

403

Correct credentials but you don't have access to the requested resource

500

Correct credentials but you don't have access to the requested resource

501

Something went wrong on our end, try again with exponential back-off

get/v1/projects/{project_id}/webhooks/{webhook_id}
Request samples
import fetch from 'node-fetch';

async function run() {
  const projectId = 'YOUR_project_id_PARAMETER';
  const webhookId = 'YOUR_webhook_id_PARAMETER';
  const resp = await fetch(
    `https://eu.conversation.api.sinch.com/v1/projects/${projectId}/webhooks/${webhookId}`,
    {
      method: 'GET',
      headers: {
        Authorization: 'Basic ' + Buffer.from('<username>:<password>').toString('base64')
      }
    }
  );

  const data = await resp.text();
  console.log(data);
}

run();
Response samples
application/json
{
  • "app_id": "string",
  • "client_credentials": {
    • "client_id": "string",
    • "client_secret": "string",
    • "endpoint": "string"
    },
  • "id": "string",
  • "secret": "string",
  • "target": "string",
  • "target_type": "DISMISS",
  • "triggers": [
    • "MESSAGE_DELIVERY"
    ]
}

Update an existing webhook

Updates an existing webhook as specified by the webhook ID.

Request
Security:
Basic
or
oAuth2
path Parameters
project_id
required
string

The unique ID of the project. You can find this on the Sinch Dashboard.

webhook_id
required
string

The unique ID of the webhook.

query Parameters
update_mask.paths
Array of strings

The set of field mask paths.

Request Body schema: application/json

Required. The Webhook to update

app_id
required
string

The app that this webhook belongs to.

target
required
string

The target url where events should be sent to. Maximum URL length is 742. The conversation-api.*.sinch.com subdomains are forbidden.

triggers
required
Array of strings (WebhookTrigger)

An array of triggers that should trigger the webhook and result in an event being sent to the target url. Refer to the list of Webhook Triggers for a complete list.

Items Enum: "UNSPECIFIED_TRIGGER" "MESSAGE_DELIVERY" "EVENT_DELIVERY" "MESSAGE_INBOUND" "EVENT_INBOUND" "CONVERSATION_START" "CONVERSATION_STOP" "CONTACT_CREATE" "CONTACT_DELETE" "CONTACT_MERGE" "CONTACT_UPDATE" "UNSUPPORTED" "OPT_IN" "OPT_OUT" "CAPABILITY" "CONVERSATION_DELETE"
object (ClientCredentials)
secret
string

Optional secret be used to sign contents of webhooks sent by the Conversation API. You can then use the secret to verify the signature.

target_type
string (WebhookTargetType)
Enum: "DISMISS" "GRPC" "HTTP"
Responses
200

A successful response.

Response Schema: application/json
app_id
required
string

The app that this webhook belongs to.

target
required
string

The target url where events should be sent to. Maximum URL length is 742. The conversation-api.*.sinch.com subdomains are forbidden.

triggers
required
Array of strings (WebhookTrigger)

An array of triggers that should trigger the webhook and result in an event being sent to the target url. Refer to the list of Webhook Triggers for a complete list.

Items Enum: "UNSPECIFIED_TRIGGER" "MESSAGE_DELIVERY" "EVENT_DELIVERY" "MESSAGE_INBOUND" "EVENT_INBOUND" "CONVERSATION_START" "CONVERSATION_STOP" "CONTACT_CREATE" "CONTACT_DELETE" "CONTACT_MERGE" "CONTACT_UPDATE" "UNSUPPORTED" "OPT_IN" "OPT_OUT" "CAPABILITY" "CONVERSATION_DELETE"
object (ClientCredentials)
id
string

The ID of the webhook.

secret
string

Optional secret be used to sign contents of webhooks sent by the Conversation API. You can then use the secret to verify the signature.

target_type
string (WebhookTargetType)
Enum: "DISMISS" "GRPC" "HTTP"
400

Malformed request

401

Incorrect credentials

403

Correct credentials but you don't have access to the requested resource

500

Correct credentials but you don't have access to the requested resource

501

Something went wrong on our end, try again with exponential back-off

patch/v1/projects/{project_id}/webhooks/{webhook_id}
Request samples
application/json
{
  • "app_id": "string",
  • "target": "string",
  • "triggers": [
    • "MESSAGE_DELIVERY"
    ]
}
Response samples
application/json
{
  • "app_id": "string",
  • "client_credentials": {
    • "client_id": "string",
    • "client_secret": "string",
    • "endpoint": "string"
    },
  • "id": "string",
  • "secret": "string",
  • "target": "string",
  • "target_type": "DISMISS",
  • "triggers": [
    • "MESSAGE_DELIVERY"
    ]
}

Delete an existing webhook

Deletes a webhook as specified by the webhook ID.

Request
Security:
Basic
or
oAuth2
path Parameters
project_id
required
string

The unique ID of the project. You can find this on the Sinch Dashboard.

webhook_id
required
string

The unique ID of the webhook.

Responses
200

A successful response.

Response Schema: application/json
any
400

Malformed request

401

Incorrect credentials

403

Correct credentials but you don't have access to the requested resource

500

Correct credentials but you don't have access to the requested resource

501

Something went wrong on our end, try again with exponential back-off

delete/v1/projects/{project_id}/webhooks/{webhook_id}
Request samples
import fetch from 'node-fetch';

async function run() {
  const projectId = 'YOUR_project_id_PARAMETER';
  const webhookId = 'YOUR_webhook_id_PARAMETER';
  const resp = await fetch(
    `https://eu.conversation.api.sinch.com/v1/projects/${projectId}/webhooks/${webhookId}`,
    {
      method: 'DELETE',
      headers: {
        Authorization: 'Basic ' + Buffer.from('<username>:<password>').toString('base64')
      }
    }
  );

  const data = await resp.text();
  console.log(data);
}

run();
Response samples
application/json
null