Webhooks
/
Getting started
Last updated

Getting started

A technical guide on using webhooks in Closelink.

General introduction to webhooks

Authentication

The Closelink webhook API also uses API keys for authentication of its management endpoints, you can use the same API key as for the public API.

A webhook in Closelink defines a subscription to events for certain resources in closelink. Whenever an event occurs that matches the webhook definition, a payload will be sent to the configured url via a post-request.

We also allow limiting the webhook to certain customers using a list of ids.

Specifically, the following fields are used to define a webhook:

namestringrequired

Name of the webhook

Example: "Some webhook"
groupIdstringrequired

ID of the company group

Example: "507f1f77bcf86cd799439011"
customerIdsArray of stringsrequired

CustomerIds for which the webhook should be triggered

Example: "[507f1f77bcf86cd799439011, 507f1f77bcf86cd799439012]"
urlstringrequired

Url that should be called when the webhook is triggered

Example: "https://<your-website>/<your-webhook-endpoint>"
resourceTypesArray of stringsuniquerequired

List of resources that should trigger the webhook on change

Items Enum"DRAFT_ENQUIRY""ENQUIRY""OFFER""APPROVAL_REQUEST"
Example: "[OFFER, ENQUIRY]"
enabledbooleanrequired

Enabled state of the webhook

Example: true

Webhook payload

The payload sent to the webhook url contains information about the event that triggered the webhook, information about what changed (in the changes field) as well as the resource that was changed (data).

The data field can have a different type depending on the resource type, see the resourceType field for the type of resource.

Example for an ENQUIRY event:

dataobject(EnquiryMessage)required

Enquiry model

actionstringrequired

The type of action that triggered this webhook

Enum"CREATED""UPDATED""DELETED"
Example: "CREATED"
changesArray of objects(ValueChangeObjectObject)required
triggerobject(Trigger)
resourceTypestringrequired

The type of resource the event belongs to

Enum"DRAFT_ENQUIRY""ENQUIRY""OFFER""APPROVAL_REQUEST"
Example: "OFFER"
createdAtstring(date-time)required

When the event was thrown

Example: "2023-01-01T12:00:00Z"
webhookTimestampstring(date-time)required

When the webhook was sent

Example: "2023-01-01T12:00:01Z"
webhookIdstringrequired

Unique identifier for this webhook

Example: "507f1f77bcf86cd799439011"

Headers

The following headers are sent with every webhook execution:

Closelink-Deliverystring

Unique id of the exact webhook execution

Example: "507f1f77bcf86cd799439011"
Closelink-Eventstring

The resource type of the event

Example: "OFFER"
Closelink-Signaturestring

HMAC signature of the payload using the webhook secret

Example: "x48656C6C6F"
  1. Log in to Closelink as a group admin
  2. Go to the company group settings
  3. Scroll down to the webhooks section and click Add destination
  4. Select the desired resources and companies
  5. Copy and save the generated secret; you can use this combined with the signature header to verify the payload
  6. Now you can test the webhook by creating an event in Closelink that matches the webhook definition, and it should call your endpoint

How to create a webhook using the api

Simply call the POST /v1/webhooks endpoint with the desired data. Try it here:

Loading...

Testing

For testing we recommend using a tool like webhook.site to get a temporary url to use as a webhook destination.

Full reference

You can find the full reference here. This includes the management endpoints here and the webhook events here.

You can use the Try it out button to test the webhooks.

Previous page
Next page