How To Use Webhooks As a 3rd Party Integrator

The Pax8 Webhook service allows integrators to subscribe to near-real-time data changes across the Pax8 platform. This guide explains how to properly configure and use webhooks as an integrator. The process is largely the same as creating webhooks as a Pax8 Partner, with the main difference being the required "integrationId" and the fact that multiple partner events will trigger your webhooks. See this webhook guide for more details.

Creating Webhooks with Integration ID

When creating webhooks as an INTEGRATOR user, you must provide an integrationId parameter. This parameter is required and links your webhook to your integration.

Request Format

POST /webhooks
{
  "displayName": "My Integration Webhook",
  "url": "https://my-integration.example.com/webhook",
  "contactEmail": "[email protected]",
  "errorThreshold": 5,
  "authorization": "Bearer my-secret-token",
  "webhookTopics": [
    {
      "topic": "INVOICE",
      "filters": [
        {
          "action": "CREATED",
          "conditions": []
        }
      ]
    }
  ],
  "active": true,
  "integrationId": "550e8400-e29b-41d4-a716-446655440000"
}

Key Points for Integrators

Required Integration ID

As an INTEGRATOR, you must provide your integrationId when creating webhooks. The system will validate this requirement and reject requests without a valid integration ID. This id can be provided when you create an integration application. See Integrators guide for more details.

Partner Access Control

When you create a webhook, you'll receive events for all partners that have granted you delegated authorization. The webhook system automatically filters events based on your current access permissions and provided filters.

Revocation Handling

If a partner revokes their permission to your integration, you'll continue to receive webhook events for your remaining authorized partners. The system will automatically stop sending events related to the partner who revoked access.

Topic Subscription

You can control which event topics your webhooks subscribe to by configuring the webhookTopics list in your request. This allows you to receive only the events relevant to your integration.

Webhook Configuration Options

You can customize your webhook with:

displayName: A human-readable name for your webhook
url: The destination URL where events will be sent
contactEmail: Email for notifications about webhook delivery issues
errorThreshold: Number of retry attempts (max 20) and the threshold in which we will email you
authorization: Optional authorization header to secure your endpoint
active: Whether the webhook is active or paused
integrationId: Your integration's unique identifier (required)

Webhooks as Notification Triggers, Not Data Sources

Notification System vs. Source of Truth

Webhooks in the Pax8 platform are designed as a notification system, not as a comprehensive data source. They provide minimal information about events that have occurred, serving primarily as triggers for your integration to take further action.

Key points to understand:

Webhook payloads contain only basic event information (event type, relevant IDs, timestamp)
Webhooks do not provide complete entity data or full context
The payload data is intentionally minimal to ensure fast delivery

Follow-up API Workflow Pattern

The recommended integration pattern is:

Receive webhook notification of an event
Extract the relevant identifiers from the webhook payload
Call the appropriate Pax8 public API endpoints to retrieve complete, current information
Process the full data according to your integration's requirements

This pattern ensures your integration always works with the most up-to-date and complete information.

Best Practices

Implement Idempotency: Design your webhook handler to be idempotent, as the same event may be delivered multiple times in rare circumstances.
Respond Quickly: Your endpoint should respond with a 2xx status code within 5 seconds to avoid timeouts.
Monitor Delivery Status: Use the webhook management API to check delivery status and troubleshoot issues.
Secure Your Endpoint: Use the authorization header to validate incoming webhook requests.
Set Up Alerts: Configure the contactEmail to receive notifications about persistent delivery failures.
Use Webhooks as Triggers: Treat webhooks as event notifications that should trigger API calls for complete data.
Implement Retry Logic: Add appropriate retry mechanisms when calling APIs after webhook receipt.

Troubleshooting

If you're not receiving expected events, check:

Your webhook is marked as active
You have the correct partner permissions
Your endpoint is responding with 2xx status codes
Your topic and filter configuration matches the events you want to receive
Your follow-up API calls include proper authentication and parameters