> ## Documentation Index
> Fetch the complete documentation index at: https://developers.paxoslabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

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

Paxos Labs webhooks deliver real-time HTTP notifications to your server when events occur — direct transfer deposits arrive, transactions confirm, and more. Instead of polling the API, your application reacts to events the moment they happen.

## How It Works

<Steps>
  <Step title="Register an endpoint">
    Add an HTTPS URL in the [Paxos Labs Console](https://console.paxoslabs.com) under your organization's **Webhooks** tab. You receive a signing secret on creation — store it securely.
  </Step>

  <Step title="Subscribe to events">
    Choose which event types your endpoint should receive. You can subscribe to all available events or select specific ones.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Quick Links

<CardGroup cols={3}>
  <Card title="Quick Start" icon="rocket" href="/v0.5.2/intro/webhooks/quickstart">
    Register an endpoint, subscribe to events, and handle your first webhook in minutes.
  </Card>

  <Card title="Signature Verification" icon="shield-check" href="/v0.5.2/intro/webhooks/signature-verification">
    Verify webhook authenticity with HMAC-SHA256 signatures. Includes code samples in Node.js, Python, and Go.
  </Card>

  <Card title="Event Catalog" icon="list" href="/v0.5.2/intro/webhooks/event-catalog">
    Complete reference of all webhook event types with payload schemas and examples.
  </Card>
</CardGroup>

***

## 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](/v0.5.2/intro/webhooks/signature-verification) before processing a webhook. This prevents forgery and replay attacks.

<Warning>
  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.
</Warning>

## Limits

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