Skip to main content
Use Webhooks in Dashboard to create and manage webhook integrations that receive asynchronous event notifications when events occur on the Paxos platform.
  • Each entity can have a maximum of 10 active webhooks
  • Webhook names must be unique within your account
For a complete guide on setting up webhook consumers and integrating with the Paxos platform, see the Webhooks Developer Guide.

​
View Webhooks

Navigate to the Webhooks section under the Developer tab to view all configured webhooks for your account. Each webhook displays:
  • Name: The unique identifier for your webhook
  • URL: The endpoint URL where events are delivered
  • Auth Type: The authentication method (API Key or OAuth)
  • Created At: When the webhook was created
  • Updated At: When the webhook was last updated
  • Status: Current status (Active, Pending, etc.)
  • Actions: Available actions (View, Test, Delete)
Click View to display more details about your webhook, including event types, rate limit (requests per second), and approval history.

​
Create a Webhook

Before creating a webhook in Dashboard, ensure you have a webhook consumer endpoint ready to receive events. See Create a Webhook Consumer for implementation examples. To create a new webhook:
  1. Navigate to Webhooks
  2. Click Create Webhook
  3. Configure the webhook settings:
    • Name: Enter a unique name for your webhook
    • URL: Enter your webhook consumer endpoint URL (must be HTTPS)
    • Auth Type: Select your authentication method (API Key or OAuth)
    • Authentication: Configure your selected authentication method:
      • API Key: Provide the header name and API key value that Paxos will include in webhook requests
      • OAuth: Provide the OAuth endpoint URL, Client ID, and Client Secret
    • Event Types: Select which events you want to receive (Identity, Transfer, Orchestration, etc.)
    • Rate Limit: Set the delivery rate limit (1-100 requests per second, default is 10)
  4. Click Create to save the webhook
Once created, the webhook will show an Active status and begin receiving events based on your selected event types.

​
OAuth2 client authentication

When using OAuth2 authentication, Paxos obtains access tokens by sending a POST request to the configured client_url using the OAuth2 client credentials grant. Paxos supports both standard client authentication methods and sends them simultaneously in token requests to maximize compatibility with OAuth2 providers:
MethodDescriptionFormat
client_secret_basic (recommended)Client credentials sent in the Authorization header as Basic authAuthorization: Basic base64(url_encode(client_id):url_encode(client_secret))
client_secret_postClient credentials sent in the request body as form parametersclient_id=xxx&client_secret=yyy
The request body always includes grant_type=client_credentials using application/x-www-form-urlencoded format.
Paxos supports approvals for creating and deleting webhooks. You can enable approvals for webhooks via the Admin → Approvals tab to add an additional layer of security and control.

​
Test a Webhook

After creating a webhook, use the Test feature to verify your consumer endpoint is configured correctly:
  1. Navigate to Webhooks
  2. Click Actions → Test for the webhook you want to test
  3. Select an event type to send as a test event
  4. Click Send Test Event
The test event will be sent to your endpoint with is_test=true in the payload. Verify that your consumer receives and processes the event correctly.
For information on handling test events in your consumer code, see the webhook consumer examples.

​
Update a Webhook

To update an existing webhook:
  1. Navigate to Webhooks
  2. Click View for the webhook you want to update
  3. Click Edit
  4. Modify any combination of the following settings:
    • Name: Update the webhook name
    • URL: Change the endpoint URL
    • Event Types: Add or remove event subscriptions
    • Auth Type and Credentials: Update authentication configuration
    • Rate Limit: Adjust the requests per second limit
  5. Click Update Webhook to apply your changes, or Submit for Approval if approvals are required
If approvals are enabled for webhooks, updates will require approval before taking effect.

​
Delete a Webhook

To delete a webhook:
  1. Navigate to Webhooks
  2. Click Actions → Delete for the webhook you want to remove
  3. Confirm the deletion
Once deleted, the webhook will no longer receive events and will not count toward your 10 webhook limit.

​
Errored webhooks

You should rarely see webhooks in an error state. Errors only occur when making modifications (Create, Update, or Delete) — there is no risk of webhooks randomly entering the error state once active. If this occurs, you can delete problematic webhooks and create new ones from the Dashboard.

​
Webhook Delivery and Monitoring

To view and monitor webhook events, including filtering by date, event type, and delivery status, see Events. For information about webhook delivery behavior, retry policies, and rate limits, see the Retries and Limits guide.