Webhooks

Introduction

Webhooks are the mechanism by which you can register to receive events and thus get notified instantaneously when something happens in the Xemplo application. Using webhooks will involve setting up your own hosted endpoint to receive the webhook calls.

Key Concepts

• Event: A single message received via a webhook, generally triggered within Xemplo as something occurs, like "contract created".
• Webhook: A registered receiver of events
• Callback: A URL added to a webhook registration which will receive events
• Event Type: The type of event being raised. Different callbacks can be specified to receive different types of events.

Using Webhooks

Registering Webhooks

Currently, webhooks are registered via the Create Webhook API. This is a two-step process:

1. First create the webhook for your application using Create Webhook
2. Add one or more callbacks to your webhook using Create Webhook Callback

You can have multiple event types go to a single webhook callback URL, or you can create separate URLs to receive different types of events to cater for the different event structures.

Only system administrators, or client credentials with administrator rights, are able to create webhooks.

Receiving Webhooks

Your callback should be equipped to receive HTTP POST calls with JSON content. The top-level structure is simply:

{
  "eventType": string,
  "payload": object
}

The payload data depends on the type of event being received.