Authentication and Authorisation

JWT token (OAuth)
API key

Authentication Methods for Webhooks Verification

Pleo supports the following:

HMAC Signature-Based: We support and recommend this authentication method. To learn more, click here.
Basic authentication: If the integration does not support HMAC signature-based authentication, use this method as an alternative option. To learn more, click here.
Header-based authentication: If the integration does not support HMAC signature-based authentication, you can use header-based authentication as another alternative option. To learn more, click here.

HMAC Signature-Based Authentication

In this authentication method, webhook-timsetamp and webhook-signature are sent in the request headers as unique parameters of the webhook notification.

{
    "webhook-id":"msg_p5jXN8AQM9LWM0D4loKWxJek",
    "webhook-timestamp":1614265330,
    "webhook-signature":"v1,g0hM9SsE+OTPJTGttmIKtSyZlE3uFJELVlNIOLJ1OE="
 }

Basic Authentication

In this method of authentication, the integration can send username and password in the request header of Create a Subscription request. The credentials are also included in the webhook notification sent to the configured endpoint, enabling the consumer system to validate the authenticity of the notification using the Basic Authentication mechanisms. Endpoint: POST /v1/subscriptions Request message:

{
    "status": "ACTIVE",
    "eventTypes": ["v1.export-job.created"],
    "endpointUrl": "<https://b7baf754-64e1-4469-ba23-fd7b5988eaf7.mock.pstmn.io/webhook>",
    "endpointAuth": {
        "type": "BASIC",
        "credentials": {
            "username": "your_username",
            "password": "your_password"
        }
    },
    "customHeaders": { 
        "Content-Type": "application/json" 
    }
}

Response message:

{
    "data": {
        "id": "c21a9d0e-f31b-4302-890d-751d400bbe21",
        "status": "ACTIVE",
        "eventTypes": [
            "v1.export-job.created"
        ],
        "endpointUrl": "<https://b7baf754-64e1-4469-ba23-fd7b5988eaf7.mock.pstmn.io/webhook>",
        "createdAt": "2025-03-24T16:28:23.090589Z",
        "updatedAt": "2025-03-24T16:28:23.090589Z",
			   "endpointAuth": {
			       "type": "BASIC",
			       "credentials": {
			           "username": "your_username",
			           "password": "your_password"
			       }
			   },
			   "customHeaders": { 
			       "Content-Type": "application/json" 
			   }         
    }
}

Header-based Authentication

In this method, the integration can include custom header in the request message to Create a Subscription endpoint. The headers can include API keys, bearer tokens, or any other value that the consumer system requires for authenticating the incoming webhook notification. Endpoint: POST /v1/subscriptions: Request message:

{
   "status":"ACTIVE",
   "eventTypes":[
      "v1.export-job.created"
   ],
   "endpointUrl":"<https://b7baf754-64e1-4469-ba23-fd7b5988eaf7.mock.pstmn.io/webhook>",
   "customHeaders":{
      "x-api-key":"xxxxx",
      "Authorization":"Bearer your_token",
      "Content-Type":"application/json",
      "User-Agent":"Chrome/129.0"
   }
}

Response message

{
   "data": {
      "id": "2bfde1d4-b3be-4135-960a-914b41ed2dcc",
      "status": "ACTIVE",
      "eventTypes": [
         "v1.export-job.created"
      ],
      "endpointUrl": "<https://b7baf754-64e1-4469-ba23-fd7b5988eaf7.mock.pstmn.io/webhook>",
      "createdAt": "2025-03-24T16:19:23.113886Z",
      "updatedAt": "2025-03-24T16:19:23.113886Z"
   },
   "endpointAuth": {
      "type": "NONE"
   },
   "customHeaders": {
      "x-api-key": "xxxxx",
      "Authorization": "Bearer your_token",
      "Content-Type": "application/json",
      "User-Agent": "Chrome/129.0"
   }
}

Configuring Custom Headers in New Subscription Request

While creating a new subscription request, the integration can send a custom header in the API request. For example, the integration can specify the content-type or the user-agent it wants to receive in the API response. Endpoint: Create a Subscription Request message:

{
    "status": "ACTIVE",
    "eventTypes": ["v1.export-job.created"],
    "endpointUrl": "<https://b7baf754-64e1-4469-ba23-fd7b5988eaf7.mock.pstmn.io/webhook>",
    "customHeaders": {
		    "Content-Type": "application/json",
		    "User-Agent": "Chrome/129.0"
		}
}

Response message:

{
   "data": {
      "id": "2bfde1d4-b3be-4135-960a-914b41ed2dcc",
      "status": "ACTIVE",
      "eventTypes": [
         "v1.export-job.created"
      ],
      "endpointUrl": "<https://b7baf754-64e1-4469-ba23-fd7b5988eaf7.mock.pstmn.io/webhook>",
      "createdAt": "2025-03-24T16:19:23.113886Z",
      "updatedAt": "2025-03-24T16:19:23.113886Z"
   },
   "endpointAuth": {
      "type": "NONE"
   },
   "customHeaders": {
      "Content-Type": "application/json",
      "User-Agent": "Chrome/129.0"
   }
}

ABOUT THE PLEO API

ACCOUNTING ENTRIES API

EXPORT API

TAGS API

ENRICHMENT API

TAX CODE API

APP MARKETPLACE API

EMPLOYEES API

CHART OF ACCOUNTS API

WEBHOOK SUBSCRIPTIONS API

COMPANIES API

VENDORS API

PLEO.IO API (DEPRECATED)

Authentication and Authorisation

Authentication Methods for Webhooks Verification

HMAC Signature-Based Authentication

Basic Authentication

Header-based Authentication

Configuring Custom Headers in New Subscription Request

​Authentication Methods for Webhooks Verification

​HMAC Signature-Based Authentication

​Basic Authentication

​Header-based Authentication

​Configuring Custom Headers in New Subscription Request

Authentication Methods for Webhooks Verification

HMAC Signature-Based Authentication

Basic Authentication

Header-based Authentication

Configuring Custom Headers in New Subscription Request