Webhooks

Webhooks allows a partner to receive a POST hook to a specific URL when anyone of their associated companies perform actions in Cling.

GET /partner/webhookSubscription Get the webhooks for the authenticated partner.

GET /partner/webhookSubscription/:id Get a webhook by id (replace :id with the numeric id).

POST /partner/webhookSubscription Create a new webhook.

PUT /partner/webhookSubscription/:id Update a webhook by id. Only the properties specified are updated.

DELETE /partner/webhookSubscription/:id Delete a webhoook by id

PATCH /partner/webhookSubscription/:id Undo delete a webhoook by id

Webhook properties

The model for a webhook have these properties:

{
  "id": 1,
  "type": "document.sent",
  "isActive": true,
  "url": "https://.....",
  "authType": null,
  "authData": null,
  "includePaths": ["*"],
  "conditions": null,
  "lastActiveAt": "2022-11-16T13:18:07.000Z",
  "createdAt": "2022-11-16T13:10:21.000Z",
  "updatedAt": "2022-11-16T13:10:21.000Z"
}

Property name	Description
id	Is set by Cling after Post, numeric id of the webhook. Read only.
type	The type of event to trigger on: document.created document.sent document.viewed document.answered A client answered a document document.accepted Document status was changed to accepted document.acceptedPdf document.denied document.expired document.voided companyExpense.created A new companyExpense was created (only for some accounts)
isActive	Boolean if the webhook is active or not.
url	URL to send a POST to when the webhook is triggered, must be https
authType	Optional string for authType to use, basicauth is supported.
authData	Optional JSON used when authType is specified. When authType is basicauth this must be on the format: {"username": "test", "password": "pw" }
includePaths	Array of strings to specify which data that should be included in the webhook when it is sent. [] Empty array means that no data is sent at all, just the normal id and webhook type. [”status”, "data.name”] Specify the root paths you need, in this case only document status and document name would be included. [”*”] The star is a wildcard which would pass all data in the hook (not recommended).
conditions	Optional object of conditions, used to filter which documents that should trigger this webhook. Example { 'externalReferences.*.service': 'partnerName' } to only trigger for documents that have a externalReference with a service of 'partnerName'
lastActiveAt	Read only.
createdAt	Read only.
updatedAt	Read only.

Webhook behavior and contents

When a webhook is triggered we sent the method POST to the specified URL. Respond with a valid http status to confirm that you have received the hook, if any error occur the webhook is retried again with an exponential backoff. If the hook never receive a valid http status it will after all retries be deleted and that webhook will not be triggered again.

Example

The content of the POST is on the format:

{
  "type": "document.accepted", // event type
  "typeId": "6374e2d7047992fe71a6acce", // document id
  "source": "webhookSubscription",
  "sourceId": 3, // id of the webhookSubscription
  "companyId": 25, // id of the company that did trigger
  "createdAt": "2022-11-17T09:32:22Z", // UTC
  "data": {
    // This object contains the data you specified in includePaths
    "id": "6374e2d7047992fe71a6acce",
    "status": "accepted",
    "companyId": 25,
    "data": { "name": "Document name" }
  }
}