Raise purchase orders, approve and pay invoices, and set up your workspace.

API reference

Webhooks

Have Pleaxy send each change to your HTTPS endpoint as it happens.

More about this resource

The sync feed pushed. Each event of the types an endpoint subscribes to is POSTed to it as JSON - ListSyncEvents' event plus workspaceId and documentPath, the call that reads its document - never the document itself. Every request carries Pleaxy-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<body>"> with the endpoint's secret; refuse one that doesn't match or is more than 5 minutes old. Answer with a 2xx within 10 seconds; anything else is retried after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, 12 hours and 24 hours, then given up. Endpoints are https:// addresses on a host name; deliveries never reach a private network and never follow a redirect. Up to 5 per workspace side.

Endpoints

GET…/webhooks
POST…/webhooks
PATCH…/webhooks/{webhookId}
DELETE…/webhooks/{webhookId}
POST…/webhooks/{webhookId}/secret
POST…/webhooks/{webhookId}/test
GET…/webhooks/{webhookId}/deliveries

List webhooks

Lists your webhook endpoints.

GET/v1/workspaces/{regionId}/webhooks

Returns

200 OK with the object shown in the response.

More details

Your side's endpoints and the event types they can take. Never a signing secret: secretHint shows its start and end.

A signed-in administrator (Bearer token): buyer approvalSettings edit, or a supplier administrator.

Response fields

endpoints[].eventsArray<string>
The event types sent. Empty means every type of your side, including ones added later.
endpoints[].lastErrorCodestring
Why the last attempt failed: http_status (see lastStatus), blocked_address, unreachable, timeout, redirect, too_large, endpoint_off or failed.
endpoints[].failedDeliveriesnumber
Deliveries given up in a row; a success or resuming the endpoint resets it.

Errors

403 Forbidden - An API key, or a caller who isn't an administrator of this workspace side.
401 Unauthorized - No credential was presented, or the Bearer token / X-Api-Key value is missing, invalid, expired, or revoked.

GET /v1/workspaces/{regionId}/webhooks

Request

curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/webhooks" \
  -H "X-Api-Key: $PLEAXY_API_KEY"

Response · 200 OK

{
   "endpoints": [
      {
         "id": "string",
         "url": "string",
         "description": "string",
         "events": [ "string" ],
         "enabled": boolean,
         "secretHint": "string",
         "createdAt": "string",
         "lastAttemptAt": "string",
         "lastStatus": number,
         "lastErrorCode": "string",
         "lastSuccessAt": "string",
         "failedDeliveries": number
      }
   ],
   "eventTypes": [ "string" ]
}

Create webhook

Adds a webhook endpoint and returns its signing secret, once.

POST/v1/workspaces/{regionId}/webhooks

Body

urlstringRequired
An https:// address on a host name, with no IP address, port, user name or password.
descriptionstring
Up to 100 characters, to tell endpoints apart.
eventsArray<string>
The event types to send, from eventTypes. Leave out for all of them.

Returns

201 Created with the object shown in the response.

More details

Adds an endpoint. The response carries its signing secret, shown only this once: store it in your system to check each request's signature.

A signed-in administrator (Bearer token): buyer approvalSettings edit, or a supplier administrator.

Errors

400 Bad Request - Code WEBHOOK_URL_INVALID, WEBHOOK_EVENTS_INVALID, or WEBHOOK_LIMIT (5 endpoints already).
403 Forbidden - An API key, or a caller who isn't an administrator of this workspace side.
401 Unauthorized - No credential was presented, or the Bearer token / X-Api-Key value is missing, invalid, expired, or revoked.

POST /v1/workspaces/{regionId}/webhooks

Request

curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/webhooks" \
  -H "X-Api-Key: $PLEAXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json

body.json

{
   "url": "https://erp.example.com/pleaxy",
   "description": "string",
   "events": [ "invoice.paid", "invoice.remittance_sent" ]
}

Response · 201 Created

{
   "id": "string",
   "url": "string",
   "events": [ "string" ],
   "enabled": true,
   "secret": "string",
   "secretHint": "string",
   "createdAt": "string"
}

Update webhook

Changes a webhook endpoint, or pauses and resumes it.

PATCH/v1/workspaces/{regionId}/webhooks/{webhookId}

Parameters

webhookIdstringRequired
The endpoint's id, e.g. WH-3F9A01C2.

Body

enabledboolean
false pauses the endpoint; true resumes it. url, description and events as in CreateWebhook.

Returns

200 OK with the object shown in the response.

More details

Changes an endpoint's url, description or events, or pauses it (enabled: false) and resumes it (enabled: true). Nothing is queued for a paused endpoint. Resuming resets failedDeliveries.

A signed-in administrator (Bearer token): buyer approvalSettings edit, or a supplier administrator.

Errors

400 Bad Request - Code WEBHOOK_URL_INVALID or WEBHOOK_EVENTS_INVALID.
404 Not Found - Code WEBHOOK_NOT_FOUND.
401 Unauthorized - No credential was presented, or the Bearer token / X-Api-Key value is missing, invalid, expired, or revoked.

PATCH /v1/workspaces/{regionId}/webhooks/{webhookId}

Request

curl -X PATCH "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/webhooks/{webhookId}" \
  -H "X-Api-Key: $PLEAXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json

body.json

{
   "enabled": false
}

Response · 200 OK

The endpoint, as in ListWebhooks.

Delete webhook

Removes a webhook endpoint.

DELETE/v1/workspaces/{regionId}/webhooks/{webhookId}

Parameters

webhookIdstringRequired
The endpoint's id, e.g. WH-3F9A01C2.

Returns

204 No Content with the object shown in the response.

More details

Removes an endpoint. Deliveries still waiting for it are given up.

A signed-in administrator (Bearer token): buyer approvalSettings edit, or a supplier administrator.

Errors

404 Not Found - Code WEBHOOK_NOT_FOUND.
401 Unauthorized - No credential was presented, or the Bearer token / X-Api-Key value is missing, invalid, expired, or revoked.

DELETE /v1/workspaces/{regionId}/webhooks/{webhookId}

Request

curl -X DELETE "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/webhooks/{webhookId}" \
  -H "X-Api-Key: $PLEAXY_API_KEY"

Response · 204 No Content

(no content)

Rotate webhook secret

Replaces an endpoint's signing secret.

POST/v1/workspaces/{regionId}/webhooks/{webhookId}/secret

Parameters

webhookIdstringRequired
The endpoint's id, e.g. WH-3F9A01C2.

Returns

200 OK with the object shown in the response.

More details

A new signing secret, returned this once in secret. The old one stops signing at once, so update your system right after.

A signed-in administrator (Bearer token): buyer approvalSettings edit, or a supplier administrator.

Errors

404 Not Found - Code WEBHOOK_NOT_FOUND.
401 Unauthorized - No credential was presented, or the Bearer token / X-Api-Key value is missing, invalid, expired, or revoked.

POST /v1/workspaces/{regionId}/webhooks/{webhookId}/secret

Request

curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/webhooks/{webhookId}/secret" \
  -H "X-Api-Key: $PLEAXY_API_KEY"

Response · 200 OK

The endpoint, as in ListWebhooks, plus secret.

Test webhook

Sends an endpoint a signed test ping.

POST/v1/workspaces/{regionId}/webhooks/{webhookId}/test

Parameters

webhookIdstringRequired
The endpoint's id, e.g. WH-3F9A01C2.

Returns

200 OK with the object shown in the response.

More details

Sends the endpoint a signed ping now, once, not retried, and says what it answered.

A signed-in administrator (Bearer token): buyer approvalSettings edit, or a supplier administrator.

Errors

404 Not Found - Code WEBHOOK_NOT_FOUND.
401 Unauthorized - No credential was presented, or the Bearer token / X-Api-Key value is missing, invalid, expired, or revoked.

POST /v1/workspaces/{regionId}/webhooks/{webhookId}/test

Request

curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/webhooks/{webhookId}/test" \
  -H "X-Api-Key: $PLEAXY_API_KEY"

Response · 200 OK

{
   "ok": boolean,
   "status": number,
   "errorCode": "string",
   "durationMs": number
}

List webhook deliveries

Lists an endpoint's recent deliveries.

GET/v1/workspaces/{regionId}/webhooks/{webhookId}/deliveries

Parameters

webhookIdstringRequired
The endpoint's id, e.g. WH-3F9A01C2.

Returns

200 OK with the object shown in the response.

More details

An endpoint's last 50 deliveries, newest first, kept 30 days: each event's type, status, attempts and what went wrong.

A signed-in administrator (Bearer token): buyer approvalSettings edit, or a supplier administrator.

Response fields

deliveries[].statusstring
pending: waiting for its next try (nextAttemptAt). delivered: answered with a 2xx. failed: given up.

Errors

404 Not Found - Code WEBHOOK_NOT_FOUND.
401 Unauthorized - No credential was presented, or the Bearer token / X-Api-Key value is missing, invalid, expired, or revoked.

GET /v1/workspaces/{regionId}/webhooks/{webhookId}/deliveries

Request

curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/webhooks/{webhookId}/deliveries" \
  -H "X-Api-Key: $PLEAXY_API_KEY"

Response · 200 OK

{
   "deliveries": [
      {
         "eventId": "string",
         "type": "string",
         "status": "pending" | "delivered" | "failed",
         "attempts": number,
         "createdAt": "string",
         "nextAttemptAt": "string",
         "lastAttemptAt": "string",
         "lastStatus": number,
         "lastErrorCode": "string",
         "deliveredAt": "string"
      }
   ]
}