Webhooks
Listen to events in your Metaprise account on your webhook endpoint so your integration can automatically trigger reactions.
Overview
Webhooks allow partners to subscribe to real-time notifications of specific events occurring within the Metaprise system.
Metaprise 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.
Subscribe to webhooks
To start receiving webhooks, follow these steps:
- Identify the events you want to monitor.
- Create the webhook listener endpoint on your server.
- Subscribe to the desired events by calling POST /webhook_subscriptions.
- Handle the requests from Metaprise.
1. Identify the events
Currently, Metaprise triggers notifications for the following objects and events:
Object | Events |
---|---|
accounting_connection | connected , disconnected , deauthorized , pending_auth |
approval_policy | created , deleted , process_canceled , updated |
batch_payment | status_updated |
comment | create , update |
counterpart | created , delete , metadata_update , updated |
counterpart_address | created , delete , made_default , updated |
counterpart_contact_person | created , delete , made_default , updated |
counterpart_bank_account | created , delete , updated |
2. Create a webhook listener
To receive webhooks requests from Metaprise, you must set up an HTTPS endpoint on your server. You can use one endpoint to handle several different event types at once or set up individual endpoints for specific events.
Your webhook listener endpoint must be accessible from the public Internet, accept POST requests, and expect a JSON request body with the following structure. The endpoint must also response with a 2XX status code.
{
"id": "90cc1b23-9681-40f4-a54b-4c059cd4397d",
"created_at": "2024-03-04T20:08:48.399442+00:00",
"action": "entity.onboarding_requirements.updated",
"api_version": "2024-01-31",
"entity_id": "ce0e9fc7-b3e7-4f12-ad86-bfb0725a99f0",
"description": "entity_onboarding_requirements_updated",
"object": {
"id": "ce0e9fc7-b3e7-4f12-ad86-bfb0725a99f0"
},
"object_type": "entity",
"webhook_subscription_id": "c7f37127-44e5-494a-833a-21e60585f187"
}
3. Subscribe to webhooks
To subscribe to the desired Metaprise webhook events, call POST /webhook_subscriptions with the request body containing your webhook listener url and the events you want to be notified about. If you omit event_types
, Metaprise will notify you about all events of the specified object_type
.
curl -X POST 'https://api.sandbox.metaprise.com/v1/webhook_subscriptions' \
-H 'X-Metaprise-Version: 2024-01-31' \
-H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"url": "https://example.com/your-webhook-listener",
"object_type": "entity",
"event_types": [
"created",
"updated"
]
}'
The successful response contains the id assigned to this webhook subscription and the secret that you can use to verify webhook signatures:
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
...
"secret": "whsec_Iw3mr...",
"status": "enabled",
"url": "https://example.com/your-webhook-listener"
}
4. Handle the requests
To handle the events sent by Metaprise, 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 your webhook listener endpoint returns an HTTP status code other than 2xx, Metaprise automatically retries 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, Metaprise automatically disables the corresponding webhook subscription and all further requests are canceled, including for new events.
Review webhook deliveries
Metaprise keeps a log of delivery attempts for all webhook events that partners are subscribed to. A partner can call GET /webhook_deliveries to access the webhook delivery log for the events of a specific entity:
curl -X GET 'https://api.sandbox.metaprise.com/v1/webhook_deliveries' \
-H 'X-Metaprise-Version: 2024-01-31' \
-H 'X-Metaprise-Entity-Id: ENTITY_ID' \
-H 'Authorization: Bearer YOUR_PARTNER_TOKEN'
The response 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.
Available data is limited to the last three months.
Updated 3 months ago