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.

Note: This video was recorded for an earlier version of the API, so there are minor differences in the request and response structure compared to the current API.

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.created",
  "description": "entity has been created"
}

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_subscriptions:

curl -X POST 'https://api.sandbox.monite.com/v1/webhook_subscriptions' \
     -H 'X-Monite-Version: 2024-01-31' \
     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "event_types": [
         "created"
       ],
       "object_type": "entity",
       "url": "https://yourendpointurl.com"
     }'

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

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "event_types": [
    "created"
  ],
  "object_type": "entity",
  "status": "enabled",
  "url": "https://yourendpointurl.com"
}

The default status for the newly created webhooks is enabled.

4. Handle the requests from Monite

To handle the events sent by Monite, parse the body of the requests that arrive at 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:

{
  "id": "06c003f1-6b05-415f-be6d-39ecacdddbd3",
  "created_at": "2024-03-04T20:06:48.593225+00:00",
  "action": "counterpart.created",
  "api_version": "2024-01-31",
  "entity_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "description": "counterpart has been created",
  "object": {
    "id": "f0535ce9-8cdd-4f5c-bfe2-6a7f1429fbbe"
  },
  "object_type": "counterpart",
  "webhook_subscription_id": "c7f37127-44e5-494a-833a-21e60585f187"
}

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

Retry policy

If a webhook request returns in the response a status code different than 2xx, Monite will automatically retry to send the webhook for a total of a week. The time interval between the retries follows this schedule:

• 2 minutes
• 5 minutes
• 10 minutes
• 15 minutes
• 30 minutes
• 1 hour
• 2 hours
• 4 hours
• 8 hours
• After that, the webhook will be retried every 8 hours

If the unavailability persists for a total of a week, Monite will disable all corresponding webhook events on the partner's listener endpoint, and all further requests are canceled, including for new events. Additionally, Monite also sends a notification email to the partner's email informing them of the disabled webhook events and providing details for further action. To reactivate the webhook, call POST /webhook_subscriptions/{webhook_id}/enable.

Partners can get the missed webhook events by calling GET /events?created_at**gte=<timestamp1>&created_at**lte=<timestamp2>

Enable a webhook

To enable a specific webhook, call POST /webhook_subscriptions/{webhook_id}/enable.

View webhook deliveries

After subscribing and enabling a webhook, Monite logs all delivery attempts for each webhook event a partner subscribes to. Partners can access this by making a GET request to the /webhook_deliveries endpoint as shown:

curl -X GET 'https://api.sandbox.monite.com/v1/webhook_deliveries' \
     -H 'X-Monite-Version: 2024-01-31' \
     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \

The response object contains information about how many times an event was triggered, the event ID, the status code of the last attempt, and whether or not the final attempt was successful.

Disable a webhook

To disable a specific webhook, call POST /webhook_subscriptions/{webhook_id}/disable.

List all webhooks

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

Retrieve a webhook

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

Edit a webhook

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

Delete a webhook

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