Webhooks
Send a signed request to your own server when a routing template step runs, and check on your server that it came from ProjectBrain.
A routing template can include a webhook step. When the step runs on a task, ProjectBrain sends an HTTP request to a URL you choose, for example to tell another system that a task was assigned.
Before you start
Section titled “Before you start”Allow a destination
Section titled “Allow a destination”ProjectBrain only sends webhooks to hostnames your organization has approved.
- Go to Settings > Webhooks (Webhook Allowlist).
- Add the hostname, such as
hooks.example.com, with a description. - Copy the signing secret and store it on your server.
The hostname must match exactly. A webhook to any other host fails, and the task’s activity shows why.
Add a webhook step
Section titled “Add a webhook step”In a routing template, add a step with the webhook action and set:
- URL, which can include placeholders such as
{{task.title}} - Method: POST (the default), PUT or PATCH
- Optional headers and body. With no body, the task is sent as JSON.
The workflow carries on whether the webhook succeeds or not. Each attempt shows on the task’s activity.
Verify a request came from ProjectBrain
Section titled “Verify a request came from ProjectBrain”Every request carries an X-Signature header. It is the HMAC-SHA256 of the raw request body, using that hostname’s secret, written as hex.
To check it on your server:
- Read the raw body exactly as received, before parsing it.
- Compute HMAC-SHA256 of the body with your secret.
- Compare it to
X-Signatureusing a constant-time comparison. Reject the request if it does not match.
Rotating the secret
Section titled “Rotating the secret”Rotate a secret from Settings > Webhooks if you think it has leaked. For seven days after a rotation, requests also carry X-Signature-Previous, signed with the old secret. Accept a request if either header matches, update your server to the new secret, then rely on X-Signature only.
Retries
Section titled “Retries”- A 2xx response counts as delivered.
- A 4xx response counts as failed and is not retried.
- A 5xx response, a timeout or a network error is retried a few times with growing gaps, then given up.
Respond quickly. A request that takes longer than 30 seconds is treated as failed.