# 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?](https://support.bluedeer.ai/using-bluedeer/tasks-and-inbox/what-limits-apply-to-tasks.md)

## 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?](https://support.bluedeer.ai/using-bluedeer/tasks-and-inbox/schedule-a-task.md)
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:

```bash
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

| 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-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](https://support.bluedeer.ai/using-bluedeer/tasks-and-inbox/let-a-scheduled-task-use-your-connectors.md).

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