Skip to main content
Webhooks allow you to receive Plane events in real-time via HTTP POST requests to your server. Instead of polling the events API for changes, you can subscribe to specific event types and receive data automatically when something happens.

​
Setting up webhooks

Plane uses Svix to deliver webhooks reliably. To configure webhooks:
1

Navigate to webhook settings

Go to Developers in the sidebar, then click Webhooks. You must be an admin to access this section.
2

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.
3

Select events

Choose which events you want to subscribe to. You can subscribe to all events or select specific event types.
4

Save and test

Save your endpoint configuration. Use the Test feature to send a sample event and verify your endpoint is receiving webhooks correctly.
Your organization must have API access enabled to use webhooks. Contact support if you don’t see the Webhooks option in your sidebar.

​
Webhook payload structure

All webhook payloads follow a consistent structure:
Example payload
{
  "type": "payment.created",
  "data": {
    "id": "pay_abc123",
    "amount": "1000.00",
    "currency": "USD",
    "date": "2024-01-15",
    "status": "pending",
    "worker": "wr_xyz789",
    "workspace": "ws_def456"
  }
}
​
type
string
required
The event type that triggered the webhook (e.g., payment.created, worker.updated).
​
data
object
required
The event payload containing the relevant resource data. The structure varies by event type.

​
Supported events

Webhooks can be configured for any supported event type. 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
Use the Svix client libraries to verify signatures easily in your preferred language.
Node.js verification example
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

Return a 2xx response within 30 seconds. If your processing takes longer, acknowledge receipt immediately and process the event asynchronously.
Webhooks may occasionally be delivered more than once. Use the svix-id header to deduplicate events and ensure idempotent processing.
If your endpoint returns a non-2xx response or times out, Svix will retry the delivery with exponential backoff for up to 3 days.

​
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.