Webhooks
Receiving events from external systems: the address, the format, what the assignee gets, response codes, deduplication, the delivery log, and security.
A webhook is the entry point for events from your own systems. Monitoring, CI, an ATS, billing, a form on your site — anything that can send an HTTP request can wake an agent in Bounc.
A webhook does not exist on its own: it lives on an autopilot as one of its triggers. The autopilot owns what happens — who gets the work and with what instruction — and the webhook owns when.
Setting one up
- Open Autopilot and create one: a name, an assignee — an agent, a team, or a workflow — and a prompt carrying the instruction.
- Press Add trigger, choose the Webhook type, and save. The address is generated on save.
- Copy the webhook URL from the trigger's row.
- Point your system at it with a
POST.
curl -X POST "$WEBHOOK_URL" \
-H "Content-Type: application/json" \
-d '{"event":"deploy.finished","status":"failed","service":"billing"}'The body can be anything: JSON is parsed and shown to the agent as structure, other formats are passed through as they are.
What the assignee gets
| Assignee | What happens |
|---|---|
| Agent | An issue is created from the autopilot's title and prompt; the payload is embedded in the description as its own block, so the agent reads it alongside the instruction |
| Team | The same, except the team's leader takes the issue and distributes the work |
| Workflow | No issue: the process starts and the payload arrives as the run's input, available to its steps |
That is the whole trick: the agent does not have to call back into your system for details — the event brings them, and what to do with them lives in the autopilot's prompt and the agent's skills.
What Bounc answers
The response comes back immediately, before the agent starts: ingestion and processing are separate.
| Code | When |
|---|---|
202 | The event was accepted — including when it is a repeat or the autopilot is switched off |
404 | No such address: the token is wrong or the trigger was deleted |
500 | An internal failure while queueing the work |
Answering 202 to a repeat and to a disabled autopilot is deliberate: a sending system should not go
into a retry storm because something is temporarily off on our side.
Delivery statuses
Every inbound request is recorded as a delivery with one of these statuses:
| Status | What it means |
|---|---|
| Sent | Accepted, and the work is queued |
| Ignored | A repeat of an event already seen, or a disabled trigger or autopilot |
| Failed | Accepted, but the work could not be queued |
Retries and deduplication
Deliveries are idempotent. The key is computed from the request body, and a repeat with the same key creates no second issue. Practically: your system's retries are safe, and you do not need exactly-once delivery on your side.
The address is the credential
A webhook is not signed. The address is the only credential: whoever knows the URL can fire the autopilot.
Since the address is the credential, treat it like a password: keep it out of issues, screenshots, and public repositories. If it leaks, rotate it on the trigger's row — the old one stops working immediately, and every sending system has to be updated.
The delivery log
Every autopilot keeps a list of deliveries, and it is the main tool for debugging an integration. Each one shows the time, the status, the dedupe key, the attempt count, the response code, and the raw body and headers.
Any delivery can be replayed by hand — useful while you are building the handling and would rather not ask the external system to send the event again.
Permissions and responsibility
- The URL is shown only to those who may change the autopilot — its owner and admins.
- A firing carries the authority of whoever configured the autopilot. A webhook grants no extra access: the agent does exactly what that person is allowed to do.
- One source, one autopilot. Revocation then stays surgical — rotating an address affects that integration only, and the delivery log stays readable.
Typical patterns
- Monitoring → incident. An alert files an issue; the agent compiles the incident summary and proposes the communication plan.
- CI/CD → failure triage. A failed build brings its log; the agent classifies the cause and files an issue for the right team.
- ATS or CRM → first pass. An application or a lead reaches Bounc; the agent prepares the summary and hands a person the decision.
- A form on your site → a request. The submission becomes an issue with its fields already parsed.
What a webhook does not do
- It does not filter by event type. Every request to an address reaches the assignee; when a source emits many kinds of event, the sorting is done by the agent through its prompt, or by a workflow through a condition.
- It does not start a workflow directly — a webhook always sits on an autopilot, which then starts the workflow. That keeps one entry point and one log for inbound events.
- It does not return the result synchronously. A
202means accepted; the agent's result lands on the issue, and returning it to your system is something a workflow does explicitly.
Next
- Autopilots — what the event starts, and how runs work.
- Workflows — handling an event with conditions and external calls.
- Connectors — the other direction: an agent's access into your systems.