Create and test a webhook
Create an endpoint, select events, and check that it receives and verifies deliveries.
- PlanPro or Enterprise
- WhoOwners, admins, and members
Before you create a webhook
- The workspace is on Pro or Enterprise.
- You are an owner, admin, or member. Viewers cannot open Webhooks, and a workspace policy can limit who creates them.
- The endpoint URL is public HTTPS with a valid certificate.
- The receiver can read the raw request body and store a signing secret outside source code.
- The receiver returns a 2xx response within 30 seconds.
Create a webhook
- 1.
Open Webhooks
Open Settings > Developers > Webhooks and select New webhook.
- 2.
Set the endpoint
Enter a name and an HTTPS URL, choose a project or All projects, and tick the events to send. Select Create webhook.
- 3.
Store the secret
Copy the signing secret into the receiver's secret manager. It is shown once.
- 4.
Send a test
Open the webhook's actions menu and choose Send test. Confirm the receiver returns 2xx.
Check the endpoint before relying on it
- 1.
Send the built-in test
Choose Send test and confirm the receiver records the delivery without a production side effect.
- 2.
Check duplicate handling
Process the same event ID twice and confirm the second attempt repeats no side effects.
- 3.
Trigger a real event
Create a disposable post or task in the webhook's project. Open View deliveries and confirm the event shows a 2xx status.
Verify delivery signatures
Every delivery is signed with the webhook secret using the Standard Webhooks headers webhook-id, webhook-timestamp, and webhook-signature, so a Standard Webhooks library can verify it. Verify the signature against the raw request body before doing any work. The X-Webhook-Signature headers from earlier versions are sent until 14 April 2027. The Webhooks API reference describes the headers and how to compute the signature.
To let a receiver verify deliveries without holding the webhook secret, tick Also sign with an Ed25519 key in the webhook dialog. Each delivery then also carries a v1a signature that checks against the public key shown on the webhook row. The v1 signature stays on.
Fix setup problems
- New webhook is missing
- Webhook creation is restricted by a workspace policy, or your role is viewer. Ask an owner or admin.
- Send test cannot connect
- Confirm the URL is public HTTPS, resolves from the internet, presents a valid certificate, and is not behind a firewall or login that Project Feed cannot pass.
- Signature verification fails
- Use the raw body bytes, not a parsed and reserialized copy, and the secret stored for this webhook. After regeneration, webhook-signature lists both signatures for 24 hours and the receiver must accept either. Legacy X-Webhook-Signature uses the new secret immediately.
- The test times out
- Return 2xx within 30 seconds. Move slow work to a queue and acknowledge the delivery first.