Webhooks

Overview

Webhooks allow you to subscribe to real-time notifications of specific events occurring within the Monite system.

Monite sends these events via HTTPS as a JSON payload to an endpoint set by you. You can then use these notifications to execute actions in your backend systems.

How to subscribe to webhooks

To start receiving event notifications in your system, follow these steps:

1. Identify the events you want to monitor.
2. Create a webhook endpoint in your local system.
3. Add your webhook to the settings.
4. Handle the requests from Monite.

1. Identify the events you want to monitor

Currently, Monite triggers notifications for the following objects and events:

2. Create a webhook endpoint on your local system

To receive the Monite webhooks requests you must set up an HTTPS endpoint on your local system. You can use one endpoint to handle several different event types at once or set up individual endpoints for specific events.

This endpoint must be accessible from the public Internet, accept POST requests, and expect a request with the following JSON payload structure as the body:

{
  "object_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "entity_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "object_type": "entity",
  "action": "entity.update",
  "name": "entity has been updated"
}

The possible values for action are listed in the table above.

3. Add your webhook to the settings

To add your endpoint to the partner settings and monitor a specific object, call POST /webhook_settings:

curl -X POST 'https://api.sandbox.monite.com/v1/webhook_settings' \
     -H 'X-Monite-Version: 2023-06-04' \
     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "object_type": "entity",
       "url": "https://yourendpointurl.com"
     }'

The successful 200 response contains the webhook id, in addition to the values you provided in the request:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "object_type": "entity",
  "url": "https://yourendpointurl.com"
}

4. Handle the requests from Monite

To handle the events sent by Monite, parse the body of the requests that arrive to your webhook endpoint. You can use the entity_id, object_type, and object_id to identify the affected entity and the object that was changed.

For example, the following webhook event means that an entity with ID 3fa85f64-5717-4562-b3fc-2c963f66afa6 created a new counterpart and that counterpart was assigned ID f0535ce9-8cdd-4f5c-bfe2-6a7f1429fbbe:

{
  "object_id": "f0535ce9-8cdd-4f5c-bfe2-6a7f1429fbbe",
  "entity_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "object_type": "counterpart",
  "action": "counterpart.created",
  "name": "counterpart has been created"
}

To get the full details of the created counterpart, you can then call GET /counterparts/f0535ce9-8cdd-4f5c-bfe2-6a7f1429fbbe.

List all webhooks

To get information about all the webhooks, call GET /webhook_settings.

Retrieve a webhook

To get information about a specific webhook, call GET /webhook_settings/{webhook_id}.

Edit a webhook

To edit an existing webhook, call PATCH /webhook_settings/{webhook_id}.

Delete a webhook

To delete an existing webhook, call DELETE /webhook_settings/{webhook_id}.