Webhooks

Create Webhook Subscription

Create a Webhook Subscription.

SecurityApiKeyAuth
Request
Request Body schema: application/json
required

The Webhook Subscription to be created

required
BasicAuth (object) or NoAuth (object) or TokenAuth (object) (WebhookAuthorization)

Authorization to be added as a header in the webhook request. Can be either, Basic auth, added as 'Basic base64encoded(<username>:<password>)', Token auth, added as 'Bearer <token value>', or no auth

enabled
boolean

Defines whether this Webhook Subscription is enabled or disabled. Default is true

events
Array of strings unique

The set of events this Webhook Subscription subscribes to. Allowed values: [ConversationPending, AgentUnbannedEnduser, ConversationMessageAdded, ConversationTagAdded, AgentBannedIp, ConversationAssigned, ConversationPendingExpired, ConversationTransferred, ConversationEnqueued, ConversationCreated, ConversationUnassigned, ConversationOpen, ConversationAbandoned, ConversationClosed, ConversationNoteAdded, AgentBannedEnduser, ConversationEndUserReplaced, AgentUnbannedIp, ConversationTagRemoved, ConversationRated]

name
required
string

The Webhook Subscription name

url
required
string

URL of the server that the webhook request should be sent to

Responses
201

The created Webhook Subscription

400

Invalid value extracted from request context, Invalid value for: body, Validation failure during Webhook Subscription creation

500

Internal Server Error

post/v1/webhooks
Request samples
application/json
{
  • "name": "Dashboard Integration",
  • "events": [
    • "ConversationCreated",
    • "ConversationClosed"
    ],
  • "authorization": {
    • "username": "webhook_user",
    • "password": "webhook_password",
    • "_type": "BasicAuth"
    },
  • "enabled": true
}
Response samples
application/json
{
  • "data": {
    • "id": "cb452b81-6748-40ab-af85-6559b371bc5d",
    • "name": "Dashboard Integration",
    • "subscribedEvents": [
      • "ConversationCreated",
      • "ConversationClosed"
      ],
    • "headers": {
      • "Authorization": "Basic d2ViaG9va191c2VyOndlYmhvb2tfcGFzc3dvcmQ="
      },
    • "secretKey": "4g4h988p468g785965b780684bde5546c52gge658d76b4q33fb69c526ea4bdbc",
    • "enabled": true,
    • "createdAt": "2023-08-01T09:30:15Z",
    • "createdBy": "e979cc3b-17b2-4850-b049-13c758763d1c",
    • "updatedAt": "2023-08-02T15:09:30Z",
    • "updatedBy": "64b777c3-eb82-49fb-bb3e-294afb5d840c"
    }
}

Delete Webhook Subscription

Delete a Webhook Subscription.

SecurityApiKeyAuth
Request
path Parameters
webhookSubscriptionId
required
string <uuid>
Responses
204

The Webhook Subscription was successfully deleted

400

Invalid value for: path parameter webhookSubscriptionId, Invalid value extracted from request context

404

An entity in this request could not be found

500

Internal failure during request processing

delete/v1/webhooks/{webhookSubscriptionId}
Request samples
Response samples
application/json
{
  • "message": "Invalid value in request"
}

List all Webhook Subscriptions

List of all Webhook Subscriptions in an organization.

SecurityApiKeyAuth
Responses
200

The List of Webhook Subscriptions

400

Invalid value extracted from request context

500

Internal Server Error

get/v1/webhooks
Request samples
Response samples
application/json
{
  • "data": [
    • {
      • "id": "cb452b81-6748-40ab-af85-6559b371bc5d",
      • "name": "Dashboard Integration",
      • "subscribedEvents": [
        • "ConversationCreated",
        • "ConversationClosed"
        ],
      • "headers": {
        • "Authorization": "Basic d2ViaG9va191c2VyOndlYmhvb2tfcGFzc3dvcmQ="
        },
      • "secretKey": "4g4h988p468g785965b780684bde5546c52gge658d76b4q33fb69c526ea4bdbc",
      • "enabled": true,
      • "createdAt": "2023-08-01T09:30:15Z",
      • "createdBy": "e979cc3b-17b2-4850-b049-13c758763d1c",
      • "updatedAt": "2023-08-02T15:09:30Z",
      • "updatedBy": "64b777c3-eb82-49fb-bb3e-294afb5d840c"
      }
    ]
}

Patch Webhook Subscription

Patch a Webhook Subscription.

SecurityApiKeyAuth
Request
path Parameters
webhookSubscriptionId
required
string <uuid>
Request Body schema: application/json
required

The Webhook Subscription fields to be patched

BasicAuth (object) or NoAuth (object) or TokenAuth (object) (WebhookAuthorization)

Authorization to be added as a header in the webhook request. Can be either, Basic auth, added as 'Basic base64encoded(<username>:<password>)', Token auth, added as 'Bearer <token value>', or no auth

enabled
boolean

Defines whether this Webhook Subscription is enabled or disabled

events
Array of strings unique

The set of events this Webhook Subscription subscribes to. Allowed values: [ConversationPending, AgentUnbannedEnduser, ConversationMessageAdded, ConversationTagAdded, AgentBannedIp, ConversationAssigned, ConversationPendingExpired, ConversationTransferred, ConversationEnqueued, ConversationCreated, ConversationUnassigned, ConversationOpen, ConversationAbandoned, ConversationClosed, ConversationNoteAdded, AgentBannedEnduser, ConversationEndUserReplaced, AgentUnbannedIp, ConversationTagRemoved, ConversationRated]

name
string

The Webhook Subscription name

url
string

URL of the server that the webhook request should be sent to

Responses
200

The patched Webhook Subscription

400

Invalid value for: path parameter webhookSubscriptionId, Invalid value extracted from request context, Invalid value for: body, Validation failure during Webhook Subscription patching

500

Internal Server Error

patch/v1/webhooks/{webhookSubscriptionId}
Request samples
application/json
{
  • "name": "New name",
  • "events": [
    • "ConversationNoteAdded"
    ],
  • "authorization": {
    • "value": "eyDoiGciOqGYUzI1NiJ4.eyJ0eQJRUapoYXBpIiwib4JxA5lkIjoiNTVmMmE6MmItYjU4NF33MDMxLTk2NTktOTE2M.qPoOZoQYDn4rn-akaLmVFka15JAV7TF6QT8UHOUTIy0",
    • "_type": "TokenAuth"
    }
}
Response samples
application/json
{
  • "data": {
    • "id": "cb452b81-6748-40ab-af85-6559b371bc5d",
    • "name": "New name",
    • "subscribedEvents": [
      • "ConversationNoteAdded"
      ],
    • "headers": {
      • "Authorization": "Bearer eyDoiGciOqGYUzI1NiJ4.eyJ0eQJRUapoYXBpIiwib4JxA5lkIjoiNTVmMmE6MmItYjU4NF33MDMxLTk2NTktOTE2M.qPoOZoQYDn4rn-akaLmVFka15JAV7TF6QT8UHOUTIy0"
      },
    • "secretKey": "4g4h988p468g785965b780684bde5546c52gge658d76b4q33fb69c526ea4bdbc",
    • "enabled": true,
    • "createdAt": "2023-08-01T09:30:15Z",
    • "createdBy": "e979cc3b-17b2-4850-b049-13c758763d1c",
    • "updatedAt": "2023-08-02T15:09:30Z",
    • "updatedBy": "64b777c3-eb82-49fb-bb3e-294afb5d840c"
    }
}

Webhook Subscription

Get a Webhook Subscription by ID.

SecurityApiKeyAuth
Request
path Parameters
webhookSubscriptionId
required
string <uuid>
Responses
200

The Webhook Subscription

400

Invalid value for: path parameter webhookSubscriptionId, Invalid value extracted from request context

404

An entity in this request could not be found

500

Internal Server Error

get/v1/webhooks/{webhookSubscriptionId}
Request samples
Response samples
application/json
{
  • "data": {
    • "id": "cb452b81-6748-40ab-af85-6559b371bc5d",
    • "name": "Dashboard Integration",
    • "subscribedEvents": [
      • "ConversationCreated",
      • "ConversationClosed"
      ],
    • "headers": {
      • "Authorization": "Basic d2ViaG9va191c2VyOndlYmhvb2tfcGFzc3dvcmQ="
      },
    • "secretKey": "4g4h988p468g785965b780684bde5546c52gge658d76b4q33fb69c526ea4bdbc",
    • "enabled": true,
    • "createdAt": "2023-08-01T09:30:15Z",
    • "createdBy": "e979cc3b-17b2-4850-b049-13c758763d1c",
    • "updatedAt": "2023-08-02T15:09:30Z",
    • "updatedBy": "64b777c3-eb82-49fb-bb3e-294afb5d840c"
    }
}

Webhook Subscription Event Logs

Get the latest Webhook Subscription Event logs.

SecurityApiKeyAuth
Request
path Parameters
event
required
string
webhookSubscriptionId
required
string <uuid>
Responses
200

The Webhook Subscription Event Logs

400

Invalid value for: path parameter webhookSubscriptionId, Invalid value extracted from request context

404

An entity in this request could not be found

500

Internal Server Error

get/v1/webhooks/{webhookSubscriptionId}/delivery-status/logs/{event}
Request samples
Response samples
application/json
{
  • "data": [
    • {
      • "deliveryDetail": {
        • "deliveryTimestamp": "2023-09-15T12:00:00.000Z",
        • "success": true,
        • "responseCode": 200,
        • "responseText": "OK"
        },
      • "payload": "{ \"event_id\": \"8967e0c6-fe64-4105-bf71-14ae0c256gg4\", \"event_fqn\": \"CONVERSATION_NOTE_ADDED\", \"event_version\": \"1\", \"event_timestamp\": \"2023-09-15T12:00:00.000Z\", \"organization\": { \"id\": \"g1b15dq2-bba8-48a8-a92e-852014a166r9\", \"name\": \"Your Org Name\" }, \"data\": { \"conversation\": { \"csid\": 1234, \"channel\": \"WIDGET_CHAT\", \"status\": \"OPEN\", \"direction\": \"INBOUND\", \"queue\": { \"id\": \"b5b10483-7d28-4dea-bf8d-0d88cc3bd7cc\", \"name\": \"Your Queue\" }, \"contact_point\": \"Your Contact Point\", \"requester\": { \"id\": \"ec4a2b65-0403-42b3-b054-8998325fd8ac\", \"name\": \"Test Requester\", \"email\": \"test@example.com\", \"phone\": null, \"roles\": [ \"Enduser\" ] }, \"assignee\": { \"id\": \"cccb8520-e24f-43bf-8344-49d07665d854\", \"name\": \"An Agent\", \"email\": \"agent@yourcompany.com\", \"phone\": \"+4511223344\", \"roles\": [ \"Admin\", \"TeamLead\", \"SystemAdmin\", \"Agent\" ] }, \"subject\": null, \"tags\": [], \"created_at\": \"2023-09-01T12:00:00.000Z\" }, \"note_id\": \"ac951357-5189-4707-add7-616af55698q7\", \"text\": \"Some Note Added\", \"created_at\": \"2023-09-15T12:00:00.000Z\", \"author\": { \"id\": \"cccb8520-e24f-43bf-8344-49d07665d854\", \"name\": \"An Agent\", \"email\": \"agent@yourcompany.com\", \"phone\": \"+4511223344\", \"roles\": [ \"Admin\", \"TeamLead\", \"SystemAdmin\", \"Agent\" ] } } }"
      },
    • {
      • "deliveryDetail": {
        • "deliveryTimestamp": "2023-09-15T08:00:00.000Z",
        • "success": true,
        • "responseCode": 200,
        • "responseText": "OK"
        },
      • "payload": "{ \"event_id\": \"9963e0c6-fe64-4105-bf71-14ae0c123hh5\", \"event_fqn\": \"CONVERSATION_NOTE_ADDED\", \"event_version\": \"1\", \"event_timestamp\": \"2023-09-15T08:00:00.000Z\", \"organization\": { \"id\": \"g1b15dq2-bba8-48a8-a92e-852014a166r9\", \"name\": \"Your Org Name\" }, \"data\": { \"conversation\": { \"csid\": 1234, \"channel\": \"WIDGET_CHAT\", \"status\": \"OPEN\", \"direction\": \"INBOUND\", \"queue\": { \"id\": \"b5b10483-7d28-4dea-bf8d-0d88cc3bd7cc\", \"name\": \"Your Queue\" }, \"contact_point\": \"Your Contact Point\", \"requester\": { \"id\": \"ec4a2b65-0403-42b3-b054-8998325fd8ac\", \"name\": \"Test Requester\", \"email\": \"test@example.com\", \"phone\": null, \"roles\": [ \"Enduser\" ] }, \"assignee\": { \"id\": \"cccb8520-e24f-43bf-8344-49d07665d854\", \"name\": \"An Agent\", \"email\": \"agent@yourcompany.com\", \"phone\": \"+4511223344\", \"roles\": [ \"Admin\", \"TeamLead\", \"SystemAdmin\", \"Agent\" ] }, \"subject\": null, \"tags\": [], \"created_at\": \"2023-09-01T12:00:00.000Z\" }, \"note_id\": \"ac951357-5189-4707-add7-616af55698q7\", \"text\": \"First Note\", \"created_at\": \"2023-09-15T08:00:00.000Z\", \"author\": { \"id\": \"cccb8520-e24f-43bf-8344-49d07665d854\", \"name\": \"An Agent\", \"email\": \"agent@yourcompany.com\", \"phone\": \"+4511223344\", \"roles\": [ \"Admin\", \"TeamLead\", \"SystemAdmin\", \"Agent\" ] } } }"
      }
    ]
}

Webhook Subscription Last Delivery Statuses

Get the latest delivery statuses of a Webhook Subscription.

SecurityApiKeyAuth
Request
path Parameters
webhookSubscriptionId
required
string <uuid>
Responses
200

The Latest Delivery Statuses of a Webhook Subscription

400

Invalid value for: path parameter webhookSubscriptionId, Invalid value extracted from request context

404

An entity in this request could not be found

500

Internal Server Error

get/v1/webhooks/{webhookSubscriptionId}/delivery-status
Request samples
Response samples
application/json
{
  • "data": [
    • {
      • "event": "ConversationCreated",
      • "deliveryStatus": {
        • "deliveryTimestamp": "2023-09-15T12:00:00.000Z",
        • "success": true,
        • "responseCode": 200,
        • "responseText": "OK",
        • "_type": "DeliveryDetail"
        }
      },
    • {
      • "event": "ConversationClosed",
      • "deliveryStatus": {
        • "_type": "NoRecentDelivery"
        }
      }
    ]
}