Skip to content
Open Bluedeer

Start a task from a webhook

Give a task its own secret web address, so that Stripe, GitHub, PostHog or any other service can start it by sending a request, with what it sent passed to the task.

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

  1. 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?
  2. On the task's page, click Edit.
  3. Under Schedule, choose When something happens.
  4. Under Starts when, choose A web request to the task's own address (webhook).
  5. 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, action or event.event.
  • Has the value: the value that field must have. It is compared as text, so 200, true and invoice.paid are 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-Signature header with your Stripe endpoint's signing secret.
  • GitHub signature: checks the X-Hub-Signature-256 header 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-Signature unless you enter another Header name.
  • Shared secret in a header: checks that a header holds your secret exactly. The header is X-Webhook-Secret unless 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

  1. In the Stripe Dashboard, go to Developers > Webhooks and add an endpoint.
  2. Paste the task's address as the endpoint URL.
  3. Choose the events that should start the task, for example invoice.paid.
  4. Save the endpoint, then reveal and copy its Signing secret. It starts with whsec_.
  5. In the task's editor, under Checks who sends, choose Stripe signature, paste the signing secret and click Save.
  6. If the endpoint sends several kinds of events and only one should start the task, set Only when this field to type and Has the value to invoice.paid.

Stripe's event type, such as invoice.paid, shows next to each delivery under Last deliveries.

Example: GitHub

  1. In your repository, go to Settings > Webhooks and click Add webhook.
  2. Set Payload URL to the task's address.
  3. Set Content type to application/json.
  4. Enter a long random Secret, and choose the events that should start the task.
  5. 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

  1. In PostHog, go to Data pipeline > Destinations and add an HTTP Webhook destination.
  2. Set its URL to the task's address, and choose which events it sends.
  3. To start only for one event, set Only when this field to event.event and 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-After header, 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

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-Key or webhook-id header 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.