Skip to main content
API docs by Redocly

Webhook API (1.0.0-beta1)

Download OpenAPI specification:Download

The Webhook API provides a way to manage client-defined webhooks in the Ocelot system. Webhooks are used to notify external systems about events that occur in the Ocelot system. This API allows you to create, update, delete, and list webhooks.

Webhook event Webhook

Once you created a webhook and specified events to listen to, you will receive these events on the URI you provided.

The Ocelot system will send a POST request to your URI using the provided authentication settings (as defined in the webhook configuration). The request will contain a JSON payload with the event details.

See different event types below as payload differs between the events.

Authorizations:
basicAuth
Request Body schema: application/json
required
One of
name
string
Value: "IncomingSms.received"

Event name

eventId
string

Unique identifier in Ocelot system (if this event is resend on retries, it will retain the same id)

to
string

Phone number that received the SMS

from
string

Phone number that sent the SMS

triggerType
string
Value: "Inbound"

Trigger type (always "Inbound" for this event)

message
string

SMS message content

dateTime
string <date-time>

Date and time of the event (if this event is resend on retries, it will retain the original date-time)

Request samples

Content type
application/json
Example
{
  • "name": "IncomingSms.received",
  • "eventId": "string",
  • "to": "string",
  • "from": "string",
  • "triggerType": "Inbound",
  • "message": "string",
  • "dateTime": "2019-08-24T14:15:22Z"
}

Get all webhooks

Returns an array of all currently registered webhooks (active or not).

Authorizations:
basicAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a webhook

Creates a new webhook with unique client-defined identifier.

Authorizations:
basicAuth
Request Body schema: application/json
required
id
string

Client-defined webhook identifier

matchingEvents
Array of strings
Items Enum: "IncomingSms.received" "OutboundSms.delivered" "OutboundSms.deliveryFailed" "PhoneNumber.optedOut" "PhoneNumber.optedIn"

Array of event names that will trigger the webhook.

url
string <uri>

URI to send webhook events to

WebhookBasicAuth (object) or WebhookNoAuth (object)
active
boolean

Webhook status (enabled or disabled)

Array of objects (WebhookPerOfficeOverride)

Allows to override values of some fields for specific offices (optional)

Request samples

Content type
application/json
{
  • "id": "my-incoming-sms-webhook",
  • "matchingEvents": [
    ],
  • "url": "http://example.com",
  • "auth": {
    },
  • "active": true,
  • "perOfficeOverrides": []
}

Get a webhook

Returns a webhook by its identifier.

Authorizations:
basicAuth
path Parameters
webhookId
required
string
Example: my-incoming-sms-webhook

Webhook identifier

Responses

Response samples

Content type
application/json
{
  • "id": "my-incoming-sms-webhook",
  • "matchingEvents": [
    ],
  • "url": "http://example.com",
  • "auth": {
    },
  • "active": true,
  • "perOfficeOverrides": [],
  • "created": "2019-08-24T14:15:22Z",
  • "updated": "2019-08-24T14:15:22Z"
}

Update a webhook

Updates a webhook by its identifier (also allows for renames)

Authorizations:
basicAuth
path Parameters
webhookId
required
string
Example: my-incoming-sms-webhook

Webhook identifier

Request Body schema: application/json
required
id
string

Client-defined webhook identifier

matchingEvents
Array of strings
Items Enum: "IncomingSms.received" "OutboundSms.delivered" "OutboundSms.deliveryFailed" "PhoneNumber.optedOut" "PhoneNumber.optedIn"

Array of event names that will trigger the webhook.

url
string <uri>

URI to send webhook events to

WebhookBasicAuth (object) or WebhookNoAuth (object)
active
boolean

Webhook status (enabled or disabled)

Array of objects (WebhookPerOfficeOverride)

Allows to override values of some fields for specific offices (optional)

Request samples

Content type
application/json
{
  • "id": "my-incoming-sms-webhook",
  • "matchingEvents": [
    ],
  • "url": "http://example.com",
  • "auth": {
    },
  • "active": true,
  • "perOfficeOverrides": []
}

Delete a webhook

Deletes a webhook by its identifier.

Authorizations:
basicAuth
path Parameters
webhookId
required
string
Example: my-incoming-sms-webhook

Webhook identifier

Responses