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

# Webhooks

> Receive Plane events in real-time via HTTP

Webhooks allow you to receive [Plane events](/reference/events/object) in real-time via HTTP POST requests to your server. Instead of polling the [events API](/reference/events/list) for changes, you can subscribe to specific event types and receive data automatically when something happens.

## Setting up webhooks

Plane uses [Svix](https://www.svix.com) to deliver webhooks reliably. To configure webhooks:

<Steps>
  <Step title="Navigate to webhook settings">
    Go to **Developers** in the sidebar, then click **Webhooks**. You must be an admin to access this section.
  </Step>

  <Step title="Add an endpoint">
    Click **Add Endpoint** and enter the URL where you want to receive webhook events. This must be a publicly accessible HTTPS URL.
  </Step>

  <Step title="Select events">
    Choose which events you want to subscribe to. You can subscribe to all events or select specific event types.
  </Step>

  <Step title="Save and test">
    Save your endpoint configuration. Use the **Test** feature to send a sample event and verify your endpoint is receiving webhooks correctly.
  </Step>
</Steps>

<Note>
  Webhooks are available in verified workspaces. If you do not see **Developers → Webhooks**, confirm that your organization has completed verification.
</Note>

## Webhook payload structure

All webhook payloads follow a consistent structure:

```json Example payload theme={null}
{
  "type": "payment.created",
  "data": {
    "id": "pay_abc123",
    "amount": "1000.00",
    "currency": "USD",
    "date": "2024-01-15",
    "status": "pending",
    "worker": "wr_xyz789",
    "workspace": "ws_def456"
  }
}
```

<ResponseField name="type" type="string" required>
  The event type that triggered the webhook (e.g., `payment.created`, `worker.updated`).
</ResponseField>

<ResponseField name="data" type="object" required>
  The event payload containing the relevant resource data. The structure varies by event type.
</ResponseField>

## Supported events

Webhooks can be configured for any [supported event type](/reference/events/object#event-types). See the events documentation for the full list of available events.

## Verifying webhook signatures

Svix signs all webhook payloads so you can verify they came from Plane. Each webhook includes these headers:

* `svix-id` - Unique message identifier
* `svix-timestamp` - Unix timestamp when the message was sent
* `svix-signature` - Signature for verification

<Tip>
  Use the [Svix client libraries](https://docs.svix.com/receiving/verifying-payloads/how) to verify signatures easily in your preferred language.
</Tip>

```javascript Node.js verification example theme={null}
import { Webhook } from "svix";

const wh = new Webhook("whsec_your_secret_here");

app.post("/webhook", (req, res) => {
  const payload = req.body;
  const headers = req.headers;

  try {
    const event = wh.verify(payload, headers);
    // Process the event
    console.log("Received event:", event.type);
    res.status(200).send("OK");
  } catch (err) {
    console.error("Webhook verification failed:", err.message);
    res.status(400).send("Invalid signature");
  }
});
```

## Handling webhooks

<AccordionGroup>
  <Accordion title="Respond quickly">
    Return a `2xx` response within 30 seconds. If your processing takes longer, acknowledge receipt immediately and process the event asynchronously.
  </Accordion>

  <Accordion title="Handle duplicates">
    Webhooks may occasionally be delivered more than once. Use the `svix-id` header to deduplicate events and ensure idempotent processing.
  </Accordion>

  <Accordion title="Retry behavior">
    If your endpoint returns a non-2xx response or times out, Svix will retry the delivery with exponential backoff for up to 3 days.
  </Accordion>
</AccordionGroup>

## Monitoring and debugging

The Svix dashboard provides tools to monitor your webhooks:

* **Message logs** - View all sent webhooks with payloads and responses
* **Retry controls** - Manually retry failed deliveries
* **Endpoint health** - Monitor success rates and response times

Access these tools by clicking **Webhooks** in the Developers section of your Plane dashboard.