# Webhooks API



<EndpointIndex
  names={[
  	'fetchWebhook',
  	'fetchWebhooks',
  	'createWebhook',
  	'updateWebhook',
  	'unsuspendWebhook',
  	'deleteWebhook',
  ]}
  titles={{
  	fetchWebhook: 'Fetch a Webhook',
  	fetchWebhooks: 'Fetch All Webhooks',
  	createWebhook: 'Create a Webhook',
  	updateWebhook: 'Update a Webhook',
  	deleteWebhook: 'Delete a Webhook',
  }}
/>

Fetch a Webhook [#fetch-a-webhook]

<ApiEndpoint name="fetchWebhook" title="Fetch a Webhook" />

Fetch All Webhooks [#fetch-all-webhooks]

<ApiEndpoint name="fetchWebhooks" title="Fetch All Webhooks" />

<ApiSchema name="WebhookListResponse" />

<ApiSchema name="WebhookResponse" />

<ApiSchema name="EndpointResponse" />

Create a Webhook [#create-a-webhook]

<ApiEndpoint name="createWebhook" title="Create a Webhook" />

<ApiSchema name="CreateWebhookRequest" />

<ApiSchema name="CreateEndpointRequest" />

Update a Webhook [#update-a-webhook]

<ApiEndpoint name="updateWebhook" title="Update a Webhook" />

<Callout>
  This endpoint follows Socotra Insurance Suite's add-remove semantics for updates: removals happen first, followed by additions. This means that addition takes precedence over removal if a request includes some item in both "remove" and "add".
</Callout>

<ApiSchema name="UpdateWebhookRequest" />

<ApiSchema name="UpdateEndpointRequest" />

Unsuspend Webhook [#unsuspend-webhook]

<ApiEndpoint name="unsuspendWebhook" />

Delete a Webhook [#delete-a-webhook]

<ApiEndpoint name="deleteWebhook" title="Delete a Webhook" />

See Also [#see-also]

* [Webhooks Feature Guide](/configuration/general-topics/webhooks): Webhooks feature guide
* [Events API](/api/events/events): API details, including a list of supported events
* [Diverted Events API](/api/events/diverted-events): Functionality to handle failed webhook event messages.


## API Reference

GET /event/{tenantLocator}/webhooks/{webhookLocator} — fetchWebhook
Tags: webhooks-controller
Permissions: read
Parameters:
  tenantLocator (uuid, path, required)
  webhookLocator (ulid, path, required)
Responses:
  200 WebhookResponse — OK

GET /event/{tenantLocator}/webhooks/list — fetchWebhooks
Tags: webhooks-controller
Permissions: read, list
Parameters:
  tenantLocator (uuid, path, required)
  offset (integer, query)
  count (integer, query)
  name (string, query)
  enabled (boolean, query)
  suspended (boolean, query)
  active (boolean, query)
  eventTypes (string[], query)
  extended (boolean, query)
Responses:
  200 WebhookListResponse — OK

POST /event/{tenantLocator}/webhooks — createWebhook
Tags: webhooks-controller
Permissions: write
Parameters:
  tenantLocator (uuid, path, required)
Request body (CreateWebhookRequest):
Responses:
  200 WebhookResponse — OK

PATCH /event/{tenantLocator}/webhooks/{webhookLocator} — updateWebhook
Tags: webhooks-controller
Permissions: write
Parameters:
  tenantLocator (uuid, path, required)
  webhookLocator (ulid, path, required)
Request body (UpdateWebhookRequest):
Responses:
  200 WebhookResponse — OK

PATCH /event/{tenantLocator}/webhooks/{webhookLocator}/unsuspend — unsuspendWebhook
Tags: webhooks-controller
Permissions: write
Parameters:
  tenantLocator (uuid, path, required)
  webhookLocator (ulid, path, required)
Responses:
  204 — No Content

DELETE /event/{tenantLocator}/webhooks/{webhookLocator} — deleteWebhook
Tags: webhooks-controller
Permissions: write
Parameters:
  tenantLocator (uuid, path, required)
  webhookLocator (ulid, path, required)
Responses:
  204 — No Content

WebhookListResponse
Properties:
  listCompleted (boolean, required)
  items (WebhookResponse[], required)

WebhookResponse
Properties:
  locator (ulid, required)
  name (string, required)
  enabled (boolean, required)
  suspended (boolean, required)
  suspendedAt (datetime, required)
  eventTypes (string[], required)
  endpoint (EndpointResponse, required)
  failureHandling (FailureHandlingResponse, required)

EndpointResponse
Properties:
  url (string, required)
  headers (map<string, string[]>, required)
  secureSsl (boolean, required)
  hmacEnabled (boolean, required)
  secret (string, required)
  tag (string, required)

CreateWebhookRequest
Properties:
  name (string, required)
  enabled (boolean, required)
  eventTypes (string[], required)
  endpoint (CreateEndpointRequest, required)
  failureHandling (FailureHandlingCreateRequest, required)
  useAutomationPlugin (boolean)

CreateEndpointRequest
Properties:
  url (string, required)
  headers (map<string, string[]>)
  secureSsl (boolean)
  hmacEnabled (boolean)
  secret (string)
  tag (string)

UpdateWebhookRequest
Properties:
  name (string, required)
  enabled (boolean, required)
  removeEventTypes (string[], required)
  addEventTypes (string[], required)
  endpoint (UpdateEndpointRequest, required)
  removeFailureHandling (boolean, required)
  failureHandling (FailureHandlingUpdateRequest, required)

UpdateEndpointRequest
Properties:
  url (string, required)
  removeHeaders (string[], required)
  addHeaders (map<string, string[]>, required)
  secureSsl (boolean)
  hmacEnabled (boolean)
  secret (string)
  tag (string)