A webhook is a web request that another service sends when something happens on its side, such as a paid invoice in Stripe or a new issue in GitHub. A task can have its own secret address for these requests. Each request that reaches the address starts the task, and the task's AI receives what the service sent (the request body) together with the task's instructions.
Tasks that start when something happens need a plan that includes scheduled tasks. Scheduled tasks are included on paid plans by default; your plan page shows what your plan includes. See What limits apply to scheduled tasks?
Create the task
- Create the task by asking Bluedeer in a chat, for example "When Stripe tells me an invoice was paid, add a row to my sales sheet", or open an existing task. See How do I schedule a task?
- On the task's page, click Edit.
- Under Schedule, choose When something happens.
- Under Starts when, choose A web request to the task's own address (webhook).
- Optionally fill in Only when (see below), then click Save.
Until the task is saved this way, the editor says "The address appears here once you save the task." Open Edit again to see the Webhook address section. The same section is in the phone app, in the task's editor.
Only the person who created the task can see its address and change its settings.
Copy the address and keep it secret
The Webhook address section shows the address with most of it hidden. The very first time you open it, and right after you make a new address, it shows the whole address once, with the note "Copy it now or later with Copy; only you can see it."
- Click Copy to copy the whole address at any time. The button shows Copied for a moment.
- Anyone who has the address can send requests to it, so treat it like a password. Paste it only into the service that should call it.
- If the address may have leaked, click Make a new address and confirm. The old address stops working at once: requests to it are answered with 404 Not Found. Paste the new address into every service that used the old one.
Start only for some requests: "Only when"
By default every request starts the task. To start it only for some requests, fill in the two fields under Only when:
- Only when this field: the path of a field in the request body, with dots between levels. For example
type,actionorevent.event. - Has the value: the value that field must have. It is compared as text, so
200,trueandinvoice.paidare all compared exactly as written.
A request whose field is missing or has another value is accepted but starts nothing. It shows as Nothing started under Last deliveries.
Check who sends: verification
Under Checks who sends, choose how Bluedeer makes sure a request really comes from your service, then enter the secret and click Save. The secret is never shown again after you save it; the field then says "A secret is set". Leave the field empty to keep the stored secret, or type a new one to replace it. A secret is 8 to 512 characters long, with no line breaks.
- None: no check. Anyone who has the address can start the task.
- Stripe signature: checks the
Stripe-Signatureheader with your Stripe endpoint's signing secret. - GitHub signature: checks the
X-Hub-Signature-256header with your GitHub webhook's secret. - HMAC-SHA256 signature: checks a header that holds the HMAC-SHA256 signature of the request body, made with your secret. The header is
X-Signatureunless you enter another Header name. - Shared secret in a header: checks that a header holds your secret exactly. The header is
X-Webhook-Secretunless you enter another Header name.
A request that fails the check is refused with 401 Unauthorized, starts nothing and shows as Refused under Last deliveries, with the reason.
Example: Stripe
- In the Stripe Dashboard, go to Developers > Webhooks and add an endpoint.
- Paste the task's address as the endpoint URL.
- Choose the events that should start the task, for example
invoice.paid. - Save the endpoint, then reveal and copy its Signing secret. It starts with
whsec_. - In the task's editor, under Checks who sends, choose Stripe signature, paste the signing secret and click Save.
- If the endpoint sends several kinds of events and only one should start the task, set Only when this field to
typeand Has the value toinvoice.paid.
Stripe's event type, such as invoice.paid, shows next to each delivery under Last deliveries.
Example: GitHub
- In your repository, go to Settings > Webhooks and click Add webhook.
- Set Payload URL to the task's address.
- Set Content type to
application/json. - Enter a long random Secret, and choose the events that should start the task.
- In the task's editor, under Checks who sends, choose GitHub signature, paste the same secret and click Save.
The event name shows under Last deliveries as the event and its action, for example issues.opened. To start only for newly opened issues, set Only when this field to action and Has the value to opened.
Example: PostHog
- In PostHog, go to Data pipeline > Destinations and add an HTTP Webhook destination.
- Set its URL to the task's address, and choose which events it sends.
- To start only for one event, set Only when this field to
event.eventand Has the value to the event's name, for example$pageview. The field path depends on the body your destination sends; check a delivery to see it.
PostHog does not sign its requests. If your destination lets you add a custom header, add one such as X-Webhook-Secret with a long random value, and choose Shared secret in a header with the same header name and value. Otherwise choose None and keep the address private.
Example: curl
The editor shows a ready-made curl command; its Copy button copies it with the whole address. A request looks like this:
curl -X POST "https://…your task's address…" \
-H "Content-Type: application/json" \
-d '{"type": "invoice.paid", "amount": 4200}'
Send a test in the editor sends a small test request from Bluedeer itself. It shows with a Test tag under Last deliveries. You can send a limited number of tests in a minute.
Last deliveries
Last deliveries lists the 20 most recent requests, newest first. Each line shows when it came (in your own time zone), what happened, the HTTP status the sender got, the size of the body and the event type when the service sent one. Click the refresh button to read the list again. Before the first request, it says "Nothing has called this address yet."
What happened is one of:
- Started: the request started the task.
- Repeat, ignored: the same request came again, so it started nothing (see below).
- Nothing started: the request was accepted but started nothing, for example because of Only when, a paused task or a limit. The reason shows on the line, such as Limit reached.
- Refused: the request was turned away, for example because its signature was wrong, its body was too large or it came too often. The reason shows on the line.
Limits
- The request body has a size limit. Bluedeer reads JSON, form data (
application/x-www-form-urlencoded) and plain text. - Each address takes a limited number of requests a minute and an hour, and each workspace a limited number a minute across all its addresses. A request over these limits is answered with 429 Too Many Requests and a
Retry-Afterheader, so the sender tries again later. Last deliveries shows at most one "Too many requests" line a minute for these. - Your plan's daily limit of runs started by events applies too. Requests after that limit are still accepted (202 Accepted), but start nothing, and show Limit reached under Last deliveries.
What the sender is told
| Answer | When |
|---|---|
| 202 Accepted | The request was received. This includes requests that start nothing: a paused task, an Only when miss, a repeat, the daily limit, or an owner who no longer has access to the workspace. |
| 400 Bad Request | The body could not be read, for example broken JSON. |
| 401 Unauthorized | The signature or shared secret is missing or wrong. |
| 404 Not Found | The address is unknown or was replaced, or the task was deleted. |
| 405 Method Not Allowed | The request was not a POST. |
| 408 Request Timeout | The body took longer than 10 seconds to arrive. |
| 413 Content Too Large | The body is over the size limit. |
| 415 Unsupported Media Type | The body is not JSON, form data or plain text. |
| 429 Too Many Requests | The address or the workspace is over its per-minute or per-hour limit. Try again after the Retry-After time. |
Repeats
Services often send the same event again when they are not sure it arrived. Bluedeer starts the task only once for each event. It recognizes a repeat by:
- the event's own ID for Stripe,
- the delivery ID for GitHub,
- an
Idempotency-Keyorwebhook-idheader for any other sender, - otherwise, the same body arriving again within 10 minutes.
A repeat is answered as accepted, so the sender stops retrying, and shows as Repeat, ignored.
Paused, deleted or grouped
- While the task is Paused, requests are accepted (202 Accepted) but start nothing.
- When the task is canceled or deleted, or after you made a new address, the old address answers 404 Not Found.
- If the task is set to Group events over a number of seconds, requests that arrive within that time of the first one start one run together.
Safety
The task's AI treats the request body as untrusted data: it reads it as information, never as instructions, so a request cannot tell the task to do something else. Your workspace's rules, and the actions that need permission or an approver, apply to runs started by a webhook exactly as to any other run. See Let a scheduled task use your connectors.
Activity
In a shared workspace, making a new address and changing how the address checks senders both appear in the workspace's Activity, with who did it. The address and the secret themselves never appear there.