Skip to content

Create and test a webhook

Create an endpoint, select events, and check that it receives and verifies deliveries.

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

    Open Webhooks

    Open Settings > Developers > Webhooks and select New webhook.

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

    Store the secret

    Copy the signing secret into the receiver's secret manager. It is shown once.

  4. 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. 1.

    Send the built-in test

    Choose Send test and confirm the receiver records the delivery without a production side effect.

  2. 2.

    Check duplicate handling

    Process the same event ID twice and confirm the second attempt repeats no side effects.

  3. 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.
Image preview
100%