💡

This is a beta release.

We might have a few changes in the final release, based on your recommendations and suggestions.

Introduction

💡

For Subscriptions API endpoints reference information, see here.

When you are integrating with Pleo, you might want to receive real-time notifications for events that occur in Pleo; these webhook notifications can help you to organise and manage actions in your applications. The intent is to ensure seamless integration, data synchronisation across multiple applications, and automated workflows, eliminating the need of manual intervention.

To receive webhook notifications, you must configure a receiving endpoint and register a subscription.

Here is an example for your understanding:

When a user clicks Export in the Pleo application, the accounting data of a customer is exported to another application. And, the v1.export-job.created event is triggered. If you have subscribed to this event, webhook notifications are automatically sent to the endpoints you have configured. Hence, you do not need to poll GET <https://external.pleo.io/v1/export-jobs>.

⚠️

Note: In a single subscription request, you can:

• set only one client per customer.
• subscribe to multiple events.

How Webhooks Function?

The following diagram explains the workflow among a customer, third-party integration (third-party application + target endpoint), and Pleo (Pleo APIs + Webhook):

💡

• Step 1 to step 4 are a one time procedure.

• Step 4: For reference information on creating subscription for webhook notification, see here .

Key Features of Pleo Webhooks

• Event subscription: If you are a Developer Partner, you can subscribe to specific events in Pleo for which you want to be notified. For example, you can subscribe to the v1.export.job-created event, which is triggered when the customer's accounting data is exported to an external application.
• Real-time notifications: When an event is triggered, it generates a webhook notification in real-time.
• Secure communication: All webhook notifications are sent over HTTPS to ensure secured data transmission.
• Webhook verification: The webhook signature and the timestamp mentioned in the request header are checked to verify the authenticity.

How to Set Up Webhook Notifications?

Perform the following to configure webhook notifications:

1. Ensure access: To subscribe to specific webhook events, you need access to the relevant API. In addition, you would also require the corresponding scopes essential to access the API. The scopes are already configured in the JWT token or the API key provided during the initial integration set up. For example, if you want to subscribe to export events, you need the export-jobs:read and export-jobs write scopes.

⚠️

Note: You can request for specific scopes during the initial integration set up; hence, you cannot update the scopes when you are creating a webhook subscription.

2. Configure endpoints: You must configure the endpoint URL(s) to which you want to send the webhook notifications. For more information, see Configuring Receiving Endpoints .
3. Subscribe events: Select the specific events for which you want to send webhook notifications. You can create a new subscription request through the POST https://external.pleo.io/v1/subscriptions endpoint. For more information, see Create a subscription .
4. Secure endpoints: We recommend that you set up verification for the incoming Pleo webhook notifications. This ensures protection from potential security threats. For more information, see Verifying Webhooks .

Configuring Receiving Endpoints

Configure the endpoints to which you want to send webhook notifications. These endpoints must conform with the following:

• Hypertext Transfer Protocol Secure (HTTPS) method
• Available in the public domain
• Accepts POST request with JSON payload

Verifying Webhooks

To ensure the authenticity of the webhook notifications generated from Pleo, we recommend you to verify the webhook signature and timestamp specified in the request header. For more information, see Svix Documentation on Webhook Verification. To perform manual authentication, see Verifying Webhooks Manually.

Source IP Addresses

If your receiving endpoint is protected by a firewall, ensure that the IP addresses listed here are whitelisted.

Configuring Webhooks During Integration

For providing an optimised experience to customers, we recommend that you configure webhook subscriptions during the integration set up. Send a request to the POST/v1 webhooks endpoint.

⚠️

Note: Use the same authentication method (JWT token for OAuth or API key) obtained during the initial integration set up for the customer.

Webhook Notifications

Once you have created the subscriptions, webhook notifications are automatically sent to the target endpoints. The response message sent to the receiving endpoints contains a HTTPS header and a JSON payload.

⚠️

Note: Currently, Pleo supports only the v1.export.job-created event. Hence, the v1.export.job-created is used here for demonstration:

API	Event Type	Description
Export API	v1.export-job.created	The event is triggered when the customer's accounting data is exported to a third-party application.

Sample Response Message

JSON
    Event Headers:
    {
        "webhook-id":"msg_p5jXN8AQM9LWM0D4loKWxJek",
        "webhook-timestamp":1614265330,
        "webhook-signature":"v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE="
    }
    Event Body:
    {
        "data": {
        "key": "value",
        .....,
    },
        "eventType": "v1.export-job.created",
        "eventId": "13d8550d-dd22-46e9-ae18-c171846ba373"
    }`
```

Header

⚠️

Note: Currently, the response header specifies svix-id, svix-timestamp and svix-signature. These would be white labelled in future.

Response Payload

The response payload contains the following parameters: