Setting Up Webhooks

Webhooks send real-time HTTP POST notifications to your endpoint whenever specific events happen in BuildChart. Instead of polling the API for changes, your server receives an instant push notification the moment something occurs — a task is completed, a project deadline is at risk, or an approval is needed.

Available Events

You can subscribe to any combination of the following events:

• task.created — A new task is added to a project.
• task.updated — Any task field is modified.
• task.status_changed — A task's status changes (e.g., Not Started to In Progress).
• task.completed — A task is marked complete.
• task.overdue — A task passes its end date without completion.
• task.deleted — A task is removed from a project.
• project.created — A new project is created.
• project.updated — Project details are changed.
• project.completed — A project is marked complete.
• project.deadline_at_risk — A dependency cascade puts the project end date at risk.
• project.member_invited — A new team member is invited.
• project.member_accepted — An invited member accepts and joins.
• action.pending_approval — An AI agent action is waiting for your review.
• action.approved — A pending action is approved.
• action.rejected — A pending action is rejected.
• action.executed — An approved action is executed.

Setting Up a Webhook

1. Go to your project settings or Account > Webhooks.
2. Click "Add Webhook".
3. Enter your endpoint URL. HTTPS is required — BuildChart will not deliver to plain HTTP endpoints.
4. Select the events you want to subscribe to.
5. Copy the webhook secret that is generated for signature verification.

Verifying Signatures

Every webhook delivery is signed with HMAC-SHA256. BuildChart includes an X-Webhook-Signature header with each request. To verify authenticity, compute the HMAC-SHA256 hash of the raw request body using your webhook secret and compare it to the header value. Always verify signatures before processing webhook payloads to prevent spoofed requests.

Delivery Log and Retries

The delivery log shows the last 100 deliveries for each webhook, including the HTTP status code returned by your endpoint. If a delivery fails (any non-2xx response or timeout), BuildChart retries automatically with exponential backoff:

• Retry 1 — 1 minute after initial failure.
• Retry 2 — 5 minutes after the first retry.
• Retry 3 — 30 minutes after the second retry.

If a webhook accumulates 100 consecutive failures, it is automatically disabled. You will receive a notification and can re-enable it after fixing your endpoint.

Testing

Use the "Send Test" button next to any configured webhook to send a sample payload to your endpoint. This lets you verify that your server is receiving and processing deliveries correctly before relying on it in production.