Webhooks

Receive real-time event notifications when activity occurs in your organization

Paxos Labs webhooks deliver real-time HTTP notifications to your server when various events occur. Use them notify your users the moment they happen, or keep your infrastructure in sync with Paxos Labs in real-time.

How It Works

1. Register an endpoint

   Add an HTTPS URL in the Paxos Labs Console under your organization’s Webhooks tab. You receive a signing secret on creation — store it securely.

2. Subscribe to events

   Choose which event types your endpoint should receive. You can subscribe to all available events or select specific ones.

3. Receive and verify

   When an event fires, Paxos Labs sends a signed POST request to your endpoint. Your server verifies the HMAC signature, then processes the payload.

Quick Links

Quick Start

Register an endpoint, subscribe to events, and handle your first webhook in minutes.

Signature Verification

Verify webhook authenticity with HMAC-SHA256 signatures. Includes code samples in Node.js, Python, and Go.

Event Catalog

Complete reference of all webhook event types with payload schemas and examples.

---

Key Concepts

Concept	Description
Endpoint	An HTTPS URL on your server that receives webhook POST requests.
Subscription	The set of event types an endpoint listens to. Each endpoint can subscribe to one or more event types.
Signing secret	A unique pxlwh_ prefixed key generated when you create an endpoint. Used to verify that requests genuinely originate from Paxos Labs.
Event	A JSON payload describing something that happened — e.g., a deposit was confirmed.
Delivery	A single attempt to send an event to your endpoint. The Paxos Labs Console shows delivery history per endpoint.

Security Model

Every webhook request is signed with your endpoint’s unique secret using HMAC-SHA256. Two headers accompany each request:

Header	Value
X-PAXOS-LABS-TIMESTAMP	Unix seconds when the event was created
X-PAXOS-LABS-SIGNATURE	v1=<hex_hmac>

Your server should always verify the signature before processing a webhook. This prevents forgery and replay attacks.

Your signing secret is shown once at creation time. Copy and store it in a secrets manager immediately. If lost, delete the endpoint and create a new one.

Limits

Limit	Value
Endpoints per organization	10
Endpoint URL protocol	HTTPS only
Endpoint name length	100 characters
Delivery timeout	10 seconds