How to use Webhook APIs

Note: Our Events/Webhook functionality is currently in Beta to Pax8 Beyond attendees only. It will be in general release starting mid July 2025.

New Pax8 events or topics are continuously being added, but if you have a need or request please email: [email protected]

We send webhook calls as soon as events or actions happen in the Pax8 platform. However, this may take up to 5 minutes for your service to receive the call.

Other general notes:

Base URL: https://api.pax8.com/api/v2/webhooks

Authentication is required for every Pax8 API request (see Authentication section).

Webhooks are marked as failed if a response is not received after 10 seconds

Webhooks are sent as a POST call with a JSON body.

Only 1 of each webhook topic can be present in a single webhook subscription. Make a new webhook subscription if you want to receive different notifications for the same topic.

Table of contents

1. Authentication
2. Topic-Definitions API
3. Creating & Managing Webhooks
4. Testing a Webhook
5. Webhook Delivery Logs
6. 3rd Party Integrators
7. Automatic Retries & Error-Threshold Email Alerts
8. Common Validation Errors & How to Avoid Them
9. Pax8 Event Permissions & Behavior
10. Frequently Asked Questions

Authentication

Calling Pax8 apis

• When making calls to Pax8 APIs the Authorization header needs to be set. To learn more about this see our Authentication docs
• The token owner must also have the permissions for the Pax8 account they are operating on, otherwise no event notifications will be emitted. For example: you can subscribe to PRODUCT events but only the products the account has access to see in the pax8 catalog.

Pax8 calling your Webhook URL

Setting the Authorization field in the webhook object will include the above header in the request to your webhook url. In your application be sure to validate that value for all calls. This is an optional field so the level of security is up to you.

Topic-Definitions API

GET /webhooks/topic-definitions

Returns the authoritative catalog of topics, actions and filterable fields that may be used when creating or updating a webhook. The payload is paged; use page, size, search, sort and topic query parameters as needed.

GET /webhooks/topic-definitions?page=0&size=25
Authorization: Bearer <token>
Accept: application/json

Successful response (truncated):

{
  "content": [
    {
      "topic": "SUBSCRIPTION",
      "name": "Subscription Events",
      "description": "Triggered when billing subscription related events occur",
      "availableFilters": [
        {
          "action": "CREATE",
          "conditions": [
            { "field": "vendorId", "operator": ["IN"], "value": "[uuid, uuid]" }
          ]
        }
      ],
      "samplePayload": { … }
    }
  ],
  "number": 0,
  "size": 25,
  "totalElements": 3,
  "totalPages": 1
}

Why this endpoint matters:

• It is forward-compatible – new topics or actions will appear here first.
• Building dynamic UI? Drive your drop-downs from topic, action and conditions arrays.
• Your create webhook calls will be rejected if you reference a topic/action/field that is not present in this catalog.
• Use this api as technical documentation on what to provide our apis

Creating & Managing Webhooks

Create

POST /webhooks

{
  "displayName": "Monthly billing listener",
  "url": "https://example.com/webhooks/pax8",
  "contactEmail": "[email protected]", // optional email to send a failure alert
  "authorization": "cGFzc3dvcmQ=",   // optional, encrypted at rest
  "active": true,  // overridden to false if no topics are supplied
  "errorThreshold": 10,  // consecutive failures before an email alert is sent
  "webhookTopics": [
    {
      "topic": "SUBSCRIPTION",
      "filters": [
        {
          "action": "CREATE",
          "conditions": [
            {
              "field": "vendorId",
              "operator": "IN",
              "value": ["d6489ab3-3e13-4fe1-84ac-08d4d8c4b802"]
            }
          ]
        }
      ]
    }
  ]
}

If successful the API returns the fully populated WebhookView object (including an auto-generated ID).

Update

• Configuration – POST /webhooks/{id}/configuration
  • Use this to change the information besides the topics, such as: displayName, contactEmail, url, and authorization
  • The authorization field is optional. However, we encourage users to place a value to validate against in your app.
• Status (activate / deactivate) – POST /webhooks/{id}/status
  • This will fail if the webhook url is null
• Add a topic – POST /webhooks/{id}/topics
  • Adds a topic that does not already exist on the webhook, otherwise it will fail. To update an existing topic filters use POST /webhooks/{id}/topics/{topicId}/configuration
• Replace all topics – PUT /webhooks/{id}/topics
  • Any existing topic in the webhook that is not included in this api call will be deleted, existing ones will be updated.
• Remove a single topic – DELETE /webhooks/{id}/topics/{topicId}

All payloads accept the same structures as the create call; only the minimal delta is required.

Delete

DELETE /webhooks/{id} – permanently removes the webhook and all associated logs.

Testing a Webhook

POST /webhooks/{id}/topics/{topic}/test

Pick a topic value from the Topic-Definitions and use that for '{topic}' value. The webhook does not need to be subscribed to that topic or be active for this to send. The URL does need to be set in order to send a test.

On execution this api queues a synthetic event using the samplePayload associated with the topic definition. The call returns immediately. Look for the logs view to see the call attempt. Check you implementation to make sure your system received the webhook call.

Any delivery errors will appear in the regular webhook logs (see next section).

Webhook Delivery Logs

WebhookDeliveryStatus values: SUCCESS, FAILED.

Fields captured per attempt include HTTP status code, error message, timestamp, and attempt number.

3rd Party Integrators

This is coming soon.

Currently this feature set is available to pax8 partner users only.

Automatic Retries & Error-Threshold Email Alerts

1. The service will attempt to deliver every event up to 21 times (initial attempt + 20 automatic retries). Back-off schedule: 10 s → 30 s → 60 s then every 60 seconds after that.
2. Setting the errorThreshold determines how many times we retry and at what point we email you. Our max is currently set to 20 with a default of 10
3. After the final failure the log status is FAILED.
4. The errorThreshold counter is incremented for each consecutive failure.
5. When the threshold is met and the webhook has a contactEmail, exactly one email alert is sent.
6. A subsequent successful delivery resets the failure counter and allows the next threshold breach to trigger a new email.

You can override the threshold (default 10) per webhook via the configuration endpoint with a max of 20.

Common Validation Errors & How to Avoid Them

Pax8 Event Permissions & Behavior

Event emission is permission sensitive.

• If the Pax8 account does not have permission to the Events object no notifications will be produced, even if webhooks exist. For example: A webhook is subscribed to a specific product, but that product gets removed from that accounts catalog but may still be active. no events will be sent for that removed product until the product is brought back to the catalog..

Frequently Asked Questions

Q – Can I create an inactive webhook first and activate it later?
Yes. Omit active or set it to false. You can activate later via POST /webhooks/{id}/status.

Q – Do you support HMAC signatures?
Not yet. Use the authorization field to embed a static secret (e.g. Bearer <token>). The service will include the header exactly as provided on every outbound call.