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

# Webhooks

> Receive real-time notifications when events occur in Dodo Payments. Automate workflows and keep your systems synchronized with instant event delivery.

<Frame>
  <img src="https://mintcdn.com/dodopayments/mOQO5ej_lx0yH9p-/images/cover-images/Webhooks.webp?fit=max&auto=format&n=mOQO5ej_lx0yH9p-&q=85&s=477435b1004773582aa51236b5cc58e7" alt="Webhook Cover Image" style={{ maxHeight: '500px', width: 'auto' }} width="1200" height="630" data-path="images/cover-images/Webhooks.webp" />
</Frame>

Webhooks provide real-time notifications when specific events occur in your Dodo Payments account. Use webhooks to automate workflows, update your database, send notifications, and keep your systems synchronized.

<Info>
  Our webhook implementation follows the [Standard Webhooks](https://standardwebhooks.com/) specification, ensuring compatibility with industry best practices and existing webhook libraries.
</Info>

## Key Features

<CardGroup cols={2}>
  <Card title="Real-time Delivery" icon="bolt">
    Receive instant notifications when events occur
  </Card>

  <Card title="Secure by Default" icon="shield-check">
    HMAC SHA256 signature verification included
  </Card>

  <Card title="Automatic Retries" icon="rotate">
    Built-in retry logic with exponential backoff
  </Card>

  <Card title="Event Filtering" icon="filter">
    Subscribe only to events you need
  </Card>
</CardGroup>

## Getting Started

<Info>
  The Dodo Payments webhooks portal has been rebuilt with a native dashboard experience. Your existing endpoints, signing secrets, signature verification, event names, and webhook payloads are unchanged. No integration work is needed.
</Info>

<Note>
  **Where things live.**

  * **Under Developer → Webhooks** — the **Endpoints**, **Event catalog**, **Logs**, **Activity**, and **Settings** tabs.
  * **On an individual endpoint** — the **Overview** tab, carrying delivery stats, the signing secret and **Replay history**, plus the **Testing** and **Advanced** tabs and the bulk replay actions.
  * **On a message** — opened from the **Logs** tab, where each delivery attempt can be replayed on its own without opening the endpoint.
</Note>

<Steps>
  <Step title="Access Webhook Settings">
    Navigate to the Dodo Payments Dashboard and go to **Developer → Webhooks**.
  </Step>

  <Step title="Create Webhook Endpoint">
    Click **Add endpoint** to open the endpoint creation side sheet.
  </Step>

  <Step title="Enter Endpoint URL or Choose Integration">
    Enter the URL where you want to receive webhook events, or select an integration connector to route events to a third-party service (Slack, Discord, Zapier, Resend, etc.).
  </Step>

  <Step title="Select Events to Receive">
    Choose the specific events your endpoint should listen for. Events are organized in a searchable tree grouped by resource. You can select individual events or a parent resource to receive all related events.

    <Tip>
      Only selected events will trigger webhooks to your endpoint, helping you avoid unnecessary traffic and processing.
    </Tip>
  </Step>

  <Step title="Create Endpoint">
    Click **Create endpoint** to save your configuration.
  </Step>

  <Step title="Get Secret Key">
    Your webhook signing secret is displayed on the endpoint's **Overview** tab. You'll use this to verify the authenticity of received webhooks.

    <Warning>
      Keep your webhook secret key secure and never expose it in client-side code or public repositories.
    </Warning>
  </Step>

  <Step title="Rotate Secret (Optional)">
    If needed, you can rotate your webhook secret for enhanced security. Click **Rotate secret**, alongside the secret on the **Overview** tab.

    <Warning>
      Rotating the secret will expire it and replace it with a new one. The old secret will only be valid for the next 24 hours. Afterward, trying to verify with the old secret will fail.
    </Warning>

    <Info>
      Use secret rotation periodically or immediately if you suspect your current secret has been compromised.
    </Info>
  </Step>
</Steps>

## Integration Connectors

Instead of building your own webhook receiver, you can route webhook events directly to third-party services using integration connectors. This eliminates the need to write and maintain custom webhook handlers for popular platforms.

### How Connectors Work

A connector carries a transformation that converts the Dodo Payments event into the shape the destination expects. Which details you supply depends on the destination:

| Connector type           | What you provide                                                    | Destinations                                                                                                                                                                                                                                         |
| ------------------------ | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Incoming webhook URL** | A webhook URL you create in the vendor's own dashboard. No API key. | [Slack](/integrations/slack), [Discord](/integrations/discord), [Microsoft Teams](/integrations/microsoft-teams), [Zapier](/integrations/zapier), [Windmill](/integrations/windmill)                                                                 |
| **Vendor API**           | An API key. The destination URL comes from the connector template.  | [Resend](/integrations/resend), [SendGrid](/integrations/sendgrid), [Segment](/integrations/segment), [Customer.io](/integrations/customer-io), [HubSpot](/integrations/hubspot), [Close CRM](/integrations/close-crm), [Loops](/integrations/loops) |

The connector picker in the dashboard shows the full set currently available to your business, so treat the table above as the destinations with step-by-step setup instructions rather than an exhaustive list. See [External Integrations](/integrations/introduction) for what each destination can do once events reach it.

### Setting Up a Connector

Pick a connector while creating or editing an endpoint, and the side sheet shows setup instructions written for that destination — for example, how to create an incoming webhook URL in Slack, or where to find your Resend API key. Before you save, run the connector transformation test to confirm the event is converted correctly for the destination.

<Tip>
  Use a connector to reach a supported destination without writing code. If you need custom logic, use a standard endpoint with a [transformation](#transformations) instead.
</Tip>

## Configuring Subscribed Events

You can configure which specific events each webhook endpoint should receive.

<Steps>
  <Step title="Navigate to Webhook Endpoints">
    Go to your Dodo Payments Dashboard and navigate to **Developer → Webhooks**.
  </Step>

  <Step title="Select Your Endpoint">
    Click on the webhook endpoint you want to configure.
  </Step>

  <Step title="Open Event Configuration">
    Click **Edit** to open the endpoint configuration side sheet.
  </Step>

  <Step title="Browse Event Types">
    The event type selector displays all available webhook events organized in a searchable tree, grouped by resource (e.g., `payment`, `subscription`, `dispute`). Use the search bar to quickly find specific events by name or keyword.
  </Step>

  <Step title="Select Events">
    Check the boxes next to the events you want to receive. You can:

    * Select individual events (e.g., `payment.succeeded`, `payment.failed`)
    * Select a parent resource to receive all related events
    * Mix and match specific events based on your needs
  </Step>

  <Step title="Save Configuration">
    Click **Save** to apply your changes, or **Cancel** to discard modifications.
  </Step>
</Steps>

<Warning>
  If you deselect all events, your webhook endpoint will not receive any notifications. Make sure to select at least the events your application needs to function properly.
</Warning>

## Event Catalog

Go to **Developer → Webhooks** and open the **Event catalog** tab. It lists every event type Dodo Payments can send, so you can see what is available before subscribing an endpoint to it. Select an event to view its schema and an example payload, which is the quickest way to check the shape of a field you plan to read.

<Card title="Webhook Events Guide" icon="list" href="/developer-resources/webhooks/intents/webhook-events-guide">
  Browse the same events as reference documentation, grouped by resource.
</Card>

## Webhook Delivery

### Timeouts

Webhooks have a **15-second timeout window** for both connection and read operations. Ensure your endpoint responds quickly to avoid timeouts.

<Tip>
  Process webhooks asynchronously by acknowledging receipt immediately with a `200` status code, then handling the actual processing in the background.
</Tip>

### Automatic Retries

If a webhook delivery fails, Dodo Payments automatically retries with exponential backoff to prevent overwhelming your system.

| Attempt | Delay       | Description                                                  |
| ------- | ----------- | ------------------------------------------------------------ |
| 1       | Immediately | First retry happens right away                               |
| 2       | 5 seconds   | Second attempt after short delay                             |
| 3       | 5 minutes   | Third attempt with increased backoff                         |
| 4       | 30 minutes  | Fourth attempt continuing backoff                            |
| 5       | 2 hours     | Fifth attempt with extended delay                            |
| 6       | 5 hours     | Sixth attempt with longer delay                              |
| 7       | 10 hours    | Seventh attempt with maximum delay                           |
| 8       | 10 hours    | **Final attempt** - webhook marked as failed if unsuccessful |

<Info>
  **Maximum of 8 retry attempts** per webhook event. For example, if a webhook fails three times before succeeding, the total delivery time is approximately 35 minutes and 5 seconds from the first attempt.
</Info>

<Tip>
  Use the Dodo Payments dashboard to manually retry individual messages or bulk recover all failed messages at any time.
</Tip>

### Idempotency

Each webhook event includes a unique `webhook-id` header. Use this identifier to implement idempotency and prevent duplicate processing.

```javascript theme={null}
// Example: Storing webhook IDs to prevent duplicate processing
const processedWebhooks = new Set();

app.post('/webhook', (req, res) => {
  const webhookId = req.headers['webhook-id'];
  
  if (processedWebhooks.has(webhookId)) {
    return res.status(200).json({ received: true });
  }
  
  processedWebhooks.add(webhookId);
  // Process the webhook...
});
```

<Warning>
  Always implement idempotency checks. Due to retries, you may receive the same event multiple times.
</Warning>

### Event Ordering

Webhook events may arrive out of order due to retries or network conditions. Design your system to handle events in any sequence.

<Info>
  You will receive the **latest payload at the time of delivery**, regardless of when the webhook event was originally emitted.
</Info>

## Securing Webhooks

To ensure the security of your webhooks, always validate the payloads and use HTTPS.

### Verifying Signatures

Each webhook request includes a `webhook-signature` header, an HMAC SHA256 signature of the webhook payload and timestamp, signed with your secret key.

#### SDK verification (recommended)

All official SDKs include built‑in helpers to securely validate and parse incoming webhooks. Two methods are available:

* `unwrap()`: Verifies signatures using your webhook secret key
* `unsafe_unwrap()`: Parses payloads without verification

<Tip>
  Provide your webhook secret via `DODO_PAYMENTS_WEBHOOK_KEY` when initializing the Dodo Payments client.
</Tip>

<CodeGroup>
  ```typescript TypeScript/Node.js theme={null}
  import DodoPayments from 'dodopayments';
  import express from 'express';

  const app = express();
  app.use(express.raw({ type: 'application/json' }));

  const client = new DodoPayments({
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
    webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
  });

  app.post('/webhook', async (req, res) => {
    try {
      const unwrapped = client.webhooks.unwrap(req.body.toString(), {
        headers: {
          'webhook-id': req.headers['webhook-id'] as string,
          'webhook-signature': req.headers['webhook-signature'] as string,
          'webhook-timestamp': req.headers['webhook-timestamp'] as string,
        },
      });
      res.json({ received: true });
    } catch (error) {
      res.status(401).json({ error: 'Invalid signature' });
    }
  });
  ```

  ```python Python theme={null}
  from fastapi import FastAPI, Request, HTTPException
  from dodopayments import DodoPayments
  import os

  app = FastAPI()
  client = DodoPayments(
      bearer_token=os.getenv("DODO_PAYMENTS_API_KEY"),
      environment=os.getenv("DODO_PAYMENTS_ENVIRONMENT"),
      webhook_key=os.getenv("DODO_PAYMENTS_WEBHOOK_KEY"),
  )

  @app.post("/webhook")
  async def handle_webhook(request: Request):
      try:
          unwrapped = client.webhooks.unwrap(
              await request.body(),
              headers={
                  "webhook-id": request.headers.get("webhook-id", ""),
                  "webhook-signature": request.headers.get("webhook-signature", ""),
                  "webhook-timestamp": request.headers.get("webhook-timestamp", ""),
              },
          )
          return {"received": True}
      except Exception:
          raise HTTPException(status_code=401, detail="Invalid signature")
  ```

  ```go Go theme={null}
  import (
  	"context"
  	"io"
  	"net/http"
  	"os"
  	"github.com/dodopayments/dodopayments-go"
  	"github.com/dodopayments/dodopayments-go/option"
  )

  func webhookHandler(w http.ResponseWriter, r *http.Request) {
  	client := dodopayments.NewClient(
  		option.WithBearerToken(os.Getenv("DODO_PAYMENTS_API_KEY")),
  		option.WithEnvironment(os.Getenv("DODO_PAYMENTS_ENVIRONMENT")),
  		option.WithWebhookKey(os.Getenv("DODO_PAYMENTS_WEBHOOK_KEY")),
  	)
  	rawBody, _ := io.ReadAll(r.Body)
  	if _, err := client.Webhooks.Unwrap(context.Background(), rawBody, map[string]string{
  		"webhook-id":       r.Header.Get("webhook-id"),
  		"webhook-signature": r.Header.Get("webhook-signature"),
  		"webhook-timestamp": r.Header.Get("webhook-timestamp"),
  	}); err != nil {
  		http.Error(w, "Invalid signature", http.StatusUnauthorized)
  		return
  	}
  	w.WriteHeader(http.StatusOK)
  }
  ```
</CodeGroup>

#### Manual verification (alternative)

If you are not using an SDK, you can verify signatures yourself following the Standard Webhooks spec:

1. Build the signed message by concatenating `webhook-id`, `webhook-timestamp`, and the exact raw stringified `payload`, separated by periods (`.`).
2. Compute the HMAC SHA256 of that string using your webhook secret key from the Dashboard.
3. Compare the computed signature to the `webhook-signature` header. If they match, the webhook is authentic.

<Info>
  We follow the Standard Webhooks specification. You can use their libraries to verify signatures: [https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries](https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries). For event payload formats, see the [Webhook Payload](/developer-resources/webhooks/intents/payment).
</Info>

### Source IP Addresses

Signature verification is the supported way to authenticate a webhook. It proves the request was signed with your webhook secret, which a network-level check cannot do.

Webhook deliveries are sent from a pool of source IP addresses belonging to our delivery infrastructure. That pool changes from time to time, so treat the addresses as operational detail rather than a fixed property of the integration.

<Warning>
  Do not use a source IP allowlist as your authentication mechanism. An allowlist only shows where a request came from, not that it is genuine or unmodified — verify the `webhook-signature` header on every request, as described in [Verifying Signatures](#verifying-signatures).
</Warning>

If your infrastructure sits behind a firewall that requires an explicit allowlist, keep the following in mind:

* **Do not hardcode addresses permanently.** Ranges are added and retired over time, and a stale rule silently blocks deliveries.
* **Request the current ranges** from [support@dodopayments.com](mailto:support@dodopayments.com) before you lock down a firewall, so you are working from an up-to-date list.
* **Watch for change notices.** When delivery addresses change, we notify affected merchants by email — apply those updates before the stated date to avoid dropped deliveries.
* **Keep signature verification enabled** regardless of any network rules you add.

<Tip>
  On serverless and managed hosting platforms, inbound IP filtering is often unavailable or impractical to maintain. Signature verification is the correct control in those environments, and no allowlist is required.
</Tip>

<Info>
  A blocked delivery is treated the same as any other failure and is retried on the schedule described in [Automatic Retries](#automatic-retries). If firewall rules caused deliveries to fail, you can re-send them once the rules are fixed — see [Replaying and Recovering Messages](#replaying-and-recovering-messages).
</Info>

### Responding to Webhooks

* Your webhook handler must return a `2xx status code` to acknowledge receipt of the event.
* Any other response will be treated as a failure, and the webhook will be retried.

### Best Practices

<AccordionGroup>
  <Accordion title="Use HTTPS endpoints only" icon="lock">
    Always use HTTPS URLs for webhook endpoints. HTTP endpoints are vulnerable to man-in-the-middle attacks and expose your webhook data.
  </Accordion>

  <Accordion title="Respond immediately" icon="bolt">
    Return a `200` status code immediately upon receiving the webhook. Process the event asynchronously to avoid timeouts.

    ```javascript theme={null}
    app.post('/webhook', async (req, res) => {
      // Acknowledge receipt immediately
      res.status(200).json({ received: true });
      
      // Process asynchronously
      processWebhookAsync(req.body).catch(console.error);
    });
    ```
  </Accordion>

  <Accordion title="Handle duplicate events" icon="rotate">
    Implement idempotency using the `webhook-id` header to safely process the same event multiple times without side effects.
  </Accordion>

  <Accordion title="Secure your webhook secret" icon="key">
    Store your webhook secret securely using environment variables or a secrets manager. Never commit secrets to version control.
  </Accordion>
</AccordionGroup>

## Webhook Payload Structure

Understanding the webhook payload structure helps you parse and process events correctly.

### Request Format

```http theme={null}
POST /your-webhook-url
Content-Type: application/json
```

### Headers

<ParamField header="webhook-id" type="string" required>
  Unique identifier for this webhook event. Use this for idempotency checks.
</ParamField>

<ParamField header="webhook-signature" type="string" required>
  HMAC SHA256 signature for verifying the webhook authenticity.
</ParamField>

<ParamField header="webhook-timestamp" type="string" required>
  Unix timestamp (in seconds) when the webhook was sent.
</ParamField>

### Request Body

<ResponseField name="business_id" type="string" required>
  Your Dodo Payments business identifier.
</ResponseField>

<ResponseField name="type" type="string" required>
  Event type that triggered this webhook (e.g., `payment.succeeded`, `subscription.active`).
</ResponseField>

<ResponseField name="timestamp" type="string" required>
  ISO 8601 formatted timestamp of when the event occurred.
</ResponseField>

<ResponseField name="data" type="object" required>
  Event-specific payload containing detailed information about the event.

  <Expandable title="Data object properties">
    <ResponseField name="payload_type" type="string">
      Type of resource. One of: `Payment`, `Subscription`, `Refund`, `Dispute`, `LicenseKey`, `CreditLedgerEntry`, `CreditBalanceLow`, `AbandonedCheckout`, `DunningAttempt`, `EntitlementGrant`, or `Payout`.
    </ResponseField>

    Additional fields vary by event type. See the event-specific documentation for complete schemas.
  </Expandable>
</ResponseField>

### Example Payload

```json theme={null}
{
  "business_id": "string",
  "type": "payment.succeeded | payment.failed |...",
  "timestamp": "2024-01-01T12:00:00Z",
  "data": {
    "payload_type": "Payment | Subscription | Refund | Dispute | LicenseKey | CreditLedgerEntry | CreditBalanceLow | AbandonedCheckout | DunningAttempt | EntitlementGrant | Payout",
    // ... event-specific fields (see below)
  }
}
```

<CardGroup cols={2}>
  <Card title="Event Types" icon="list" href="/developer-resources/webhooks/intents/webhook-events-guide">
    Browse all available webhook event types
  </Card>

  <Card title="Event Payloads" icon="code" href="/developer-resources/webhooks/intents/payment">
    View detailed payload schemas for each event
  </Card>

  <Card title="Handle Payment Failures" icon="screwdriver-wrench" href="/developer-resources/handle-payment-failures">
    React to `payment.failed` and recover declined payments
  </Card>
</CardGroup>

## Testing Webhooks

You can test your webhook integration directly from the Dodo Payments dashboard to ensure your endpoint is working correctly before going live.

<Steps>
  <Step title="Navigate to Webhooks">
    Go to your Dodo Payments Dashboard and navigate to **Developer → Webhooks**.
  </Step>

  <Step title="Select Your Endpoint">
    Click on your webhook endpoint to access its details page.
  </Step>

  <Step title="Open Testing Tab">
    Click on the **Testing** tab to access the webhook testing interface.
  </Step>
</Steps>

### Send an Example Event

The **Testing** tab dispatches a sample payload to this endpoint so you can verify your receiver.

<Steps>
  <Step title="Select Event Type">
    Use **Select an event type** to choose the event you want to test, for example `payment.succeeded` or `payment.failed`.
  </Step>

  <Step title="Send Example">
    Click **Send example**. The sample payload is delivered to your endpoint URL exactly like a real event, signed the same way.

    <Warning>
      Failed messages sent from the Testing tab are not retried. Use it to verify your receiver, not to test the retry schedule.
    </Warning>
  </Step>

  <Step title="Check Your Endpoint">
    The tab records when the **Last example sent** went out. Confirm the event arrived, that your signature verification passed, and that you returned a `2xx` status code.
  </Step>
</Steps>

### Implementation Example

Here's a complete Express.js implementation showing webhook verification and handling:

<CodeGroup>
  ```typescript Express.js Webhook Handler theme={null}
  import { Webhook } from "standardwebhooks";
  import express from "express";

  const app = express();
  app.use(express.json());

  const webhook = new Webhook(process.env.DODO_WEBHOOK_SECRET);

  app.post('/webhook/dodo-payments', async (req, res) => {
    try {
      // Extract webhook headers
      const webhookHeaders = {
        "webhook-id": req.headers["webhook-id"] as string,
        "webhook-signature": req.headers["webhook-signature"] as string,
        "webhook-timestamp": req.headers["webhook-timestamp"] as string,
      };

      // Verify the webhook signature
      const payload = JSON.stringify(req.body);
      await webhook.verify(payload, webhookHeaders);
      
      // Acknowledge receipt immediately
      res.status(200).json({ received: true });
      
      // Process webhook asynchronously
      processWebhookAsync(req.body).catch(console.error);
      
    } catch (error) {
      console.error('Webhook verification failed:', error);
      res.status(400).json({ error: 'Invalid signature' });
    }
  });

  async function processWebhookAsync(data: any) {
    // Handle the webhook event based on type
    switch (data.type) {
      case 'payment.succeeded':
        await handlePaymentSucceeded(data);
        break;
      case 'subscription.active':
        await handleSubscriptionActive(data);
        break;
      // Add more event handlers...
    }
  }
  ```

  ```javascript Testing Webhooks Locally theme={null}
  const { Webhook } = require("standardwebhooks");
  const axios = require("axios");
  const crypto = require("crypto");

  // Generate test webhook
  const timestamp = new Date();
  const webhookId = crypto.randomUUID();
  const payload = {
    business_id: "biz_test123",
    type: "payment.succeeded",
    timestamp: timestamp.toISOString(),
    data: {
      payload_type: "Payment",
      payment_id: "pay_test456",
      amount: 2999
    }
  };

  // Sign the payload
  const webhookSecret = process.env.DODO_WEBHOOK_SECRET;
  const webhookInstance = new Webhook(webhookSecret);
  const payloadString = JSON.stringify(payload);
  const signature = webhookInstance.sign(webhookId, timestamp, payloadString);

  // Send test webhook
  const response = await axios.post('http://localhost:3000/webhook/dodo-payments', payload, {
    headers: {
      "webhook-id": webhookId,
      "webhook-timestamp": Math.floor(timestamp.getTime() / 1000),
      "webhook-signature": signature,
      "Content-Type": "application/json"
    }
  });

  console.log("Test webhook sent successfully:", response.data);
  ```
</CodeGroup>

<Tip>
  Test your webhook handler thoroughly using the dashboard testing interface before processing production events. This helps identify and fix issues early.
</Tip>

## Testing Webhooks with the CLI

The [Dodo Payments CLI](/developer-resources/sdks/cli) provides two commands for testing webhooks during local development, without needing to leave your terminal.

### Listen for Live Webhooks Locally

Forward real webhook events from your test mode account to your local development server in real time:

```bash theme={null}
dodo wh listen
```

The CLI opens a WebSocket connection to Dodo Payments and forwards every webhook event to your local endpoint (e.g., `http://localhost:3000/webhook`), preserving all headers including signature headers for verification testing.

<Info>
  The listener only works with **test mode** API keys. Run `dodo login` and select Test Mode before using this command.
</Info>

### Trigger Mock Webhook Events

Send mock webhook payloads to any endpoint without creating real transactions:

```bash theme={null}
dodo wh trigger
```

This interactive tool lets you pick an event type and sends a realistic mock payload to your endpoint. It loops so you can test multiple events in one session.

The trigger command covers all 47 event types Dodo Payments delivers, including the subscription, payment, refund, dispute, license key, payout, credit, abandoned checkout, dunning, and entitlement grant families — see [Supported Webhook Events](/developer-resources/sdks/cli#supported-webhook-events) for the exact list.

<Warning>
  Mock webhook payloads from `dodo wh trigger` are not signed. Use `unsafe_unwrap()` instead of `unwrap()` in your webhook handler during testing only.
</Warning>

<Card title="CLI Webhook Testing Docs" icon="terminal" href="/developer-resources/sdks/cli#webhooks">
  See the full CLI webhook testing documentation
</Card>

## Advanced Settings

The **Advanced** tab provides additional configuration options for fine-tuning your webhook endpoint behavior.

### Rate Limiting (Throttling)

Control the rate at which webhook events are delivered to your endpoint to prevent overwhelming your system.

<Steps>
  <Step title="Open Advanced Tab">
    From your endpoint details page, click the **Advanced** tab.
  </Step>

  <Step title="Configure Rate Limit">
    In the "Rate Limit (throttling)" section, click **Edit** to modify the rate limit settings.

    <Info>
      By default, webhooks have no rate limit applied, meaning events are delivered as soon as they occur.
    </Info>
  </Step>

  <Step title="Set Your Limit">
    Configure your desired rate limit to control webhook delivery frequency and prevent system overload.
  </Step>
</Steps>

<Tip>
  Use rate limiting when your webhook handler needs time to process events or when you want to batch multiple events together.
</Tip>

### Custom Headers

Add custom HTTP headers to all webhook requests sent to your endpoint. This is useful for authentication, routing, or adding metadata.

<Steps>
  <Step title="Add Headers">
    In the "Custom Headers" section, enter a **Key** and **Value** for each custom header.
  </Step>

  <Step title="Add Multiple Headers">
    Click the **+** button to add additional custom headers as needed.
  </Step>
</Steps>

Your custom headers are included in all webhook requests to this endpoint.

### Transformations

Transformations allow you to modify a webhook's payload and optionally redirect it to a different URL. This powerful feature enables you to:

* Modify the payload structure before processing
* Route webhooks to different endpoints based on content
* Add or remove fields from the payload
* Transform data formats

<Steps>
  <Step title="Enable Transformations">
    Toggle the **Enabled** switch to activate the transformation feature.
  </Step>

  <Step title="Configure Transformation">
    Click **Edit transformation** to define your transformation rules using JavaScript.
  </Step>

  <Step title="Test Transformation">
    Use the transformation test interface to verify your transformation works correctly before going live.
  </Step>
</Steps>

<Warning>
  Transformations can impact webhook delivery performance. Test thoroughly and keep transformation logic simple and efficient.
</Warning>

<Tip>
  Transformations are particularly useful for:

  * Converting between different data formats
  * Filtering events based on specific criteria
  * Adding computed fields to the payload
  * Routing events to different microservices
</Tip>

## Monitoring Webhook Logs

The **Logs** tab provides comprehensive visibility into your webhook delivery status, allowing you to monitor, debug, and manage webhook events effectively.

<Steps>
  <Step title="Navigate to Logs Tab">
    Go to **Developer → Webhooks** and open the **Logs** tab.
  </Step>

  <Step title="Browse Delivery History">
    View a table of all webhook delivery attempts with columns for Event type, Message ID, Event ID, Sent at, Attempted at, Response code, and Duration.
  </Step>

  <Step title="Search and Filter">
    Use the search bar to find specific messages by ID or event type. Filter by status (Succeeded, Failed, Pending, etc.) to focus on the events you need to investigate.
  </Step>

  <Step title="View Message Details">
    Click on any message to open the message detail page, which shows:

    * The complete webhook payload
    * Every delivery attempt with response code and duration
    * Timestamp of each attempt
    * Any error messages from your endpoint

    Each attempt carries a **Replay** action, so you can re-drive that one message without leaving the page.
  </Step>
</Steps>

## Activity Monitoring

Go to **Developer → Webhooks** and open the **Activity** tab for a view of delivery performance across your endpoints.

**Delivery activity** plots attempts over time, bucketed as **Attempts per 5 minutes**, **Attempts per hour**, or **Attempts per day** depending on the window. Each bar is split by outcome, and hovering a segment shows the status, the number of attempts, and its share of the total. On an endpoint, **Delivery stats (last 24h)** on the **Overview** tab summarizes the same information for the past day.

<Tip>
  The **Error rate (24h)** column on the **Endpoints** tab tells you at a glance which endpoints need attention, before you open any of them.
</Tip>

## Replaying and Recovering Messages

How you re-drive a message depends on how many you need:

* **One message** — open it from the **Logs** tab and use the **Replay** action on the attempt. No need to open the endpoint.
* **A range of messages** — open the endpoint, since the bulk modes act on a single endpoint at a time.

### Replaying in Bulk

Open the endpoint from **Developer → Webhooks**. Three modes are available, each acting on that endpoint alone. The range you set depends on the mode:

| Mode                        | What it does                                                                                                          | What you set                                                                                                 |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| **Recover failed messages** | Replays every message to this endpoint that failed.                                                                   | A starting point: **8 hours ago**, **Yesterday**, **3 days ago**, **Last week**, or **2 weeks ago**          |
| **Replay missing messages** | Replays messages that were never dispatched to this endpoint, for example after you subscribe it to a new event type. | The same starting points                                                                                     |
| **Bulk replay messages**    | Replays messages matching the filters you choose, including ones that already delivered successfully.                 | **Since** and **Until** bounds, defaulting to the last two weeks, plus optional event types, channel, or tag |

<Steps>
  <Step title="Open More Actions">
    On the endpoint, open **More actions** and pick one of the three modes above.
  </Step>

  <Step title="Set the Range">
    Fill in the range that mode asks for, as listed in the table.
  </Step>

  <Step title="Start the Run">
    Click **Recover** or **Replay**, depending on the mode you picked.
  </Step>
</Steps>

Every run appears under **Replay history** on the endpoint's **Overview** tab, with its mode, time range, status, and the number of messages resent.

## Email Alerts

Receive an email notification when webhook deliveries to an endpoint are failing, so you can address problems before they turn into a backlog.

<Steps>
  <Step title="Navigate to Settings Tab">
    Go to **Developer → Webhooks** and open the **Settings** tab.
  </Step>

  <Step title="Find Email Alerting">
    Locate the **Email alerting** card.
  </Step>

  <Step title="Configure Email Addresses">
    Enter the addresses that should receive the alerts. Separate multiple addresses with commas, and leave the field empty to turn alerts off.
  </Step>

  <Step title="Save">
    Click **Save** to apply your changes.
  </Step>
</Steps>

<Tip>
  Enable email alerts to catch webhook delivery problems early and maintain reliable integrations.
</Tip>

## Deploy to Cloud Platforms

Ready to deploy your webhook handler to production? We provide platform-specific guides to help you deploy webhooks to popular cloud providers with best practices for each platform.

<CardGroup cols={2}>
  <Card title="Vercel" icon="triangle" href="/developer-resources/webhooks/examples/vercel-example">
    Deploy webhooks to Vercel with serverless functions
  </Card>

  <Card title="Cloudflare Workers" icon="cloud" href="/developer-resources/webhooks/examples/cloudflare-example">
    Run webhooks on Cloudflare's edge network
  </Card>

  <Card title="Supabase Edge Functions" icon="database" href="/developer-resources/webhooks/examples/supabase-example">
    Integrate webhooks with Supabase
  </Card>

  <Card title="Netlify Functions" icon="circle-nodes" href="/developer-resources/webhooks/examples/netlify-example">
    Deploy webhooks as Netlify serverless functions
  </Card>
</CardGroup>

<Info>
  Each platform guide includes environment setup, signature verification, and deployment steps specific to that provider.
</Info>

## Related API Reference

<CardGroup cols={2}>
  <Card title="Create Webhook" icon="code" href="/api-reference/webhooks/create-webhook">
    API reference for creating and configuring webhook endpoints programmatically
  </Card>

  <Card title="List Webhooks" icon="list" href="/api-reference/webhooks/list-webhooks">
    API reference for retrieving and managing your webhook endpoints
  </Card>
</CardGroup>
