> ## Documentation Index
> Fetch the complete documentation index at: https://docs.circuit.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook providers

> How a trusted provider pushes events to Circuit, so agents with a webhook trigger run on each one.

A trusted provider sends each event to `POST /triggers/<provider>` on the control-plane origin Circuit gives it, as a JSON object. Every running agent whose [`webhook` trigger](./agent-developers/getting-started/circuit-toml-reference#triggers-section) names the provider runs once per event and receives the event unchanged. Providers today: `polysights`.

### Signing

Circuit verifies every request with the [Standard Webhooks](https://www.standardwebhooks.com) scheme, using a `whsec_` secret it shares with the provider:

| Header | Value |
| - | - |
| `webhook-id` | A non-empty id, unique per event and unchanged on retries. Resending an id starts no second run. |
| `webhook-timestamp` | When the request was sent, in Unix seconds. Circuit refuses one more than 5 minutes from its clock. |
| `webhook-signature` | `v1,` and the base64 HMAC-SHA256 of `<webhook-id>.<webhook-timestamp>.<body>`, keyed with the base64-decoded secret after `whsec_`. |

Sign the exact bytes you send.

### Body

Any JSON value up to 64 KiB. Circuit passes it to agents as `payload` and reads nothing from it, so the provider can add fields or event types without a Circuit change; a `type` field lets agents tell event kinds apart. Polysights' `insider_flag` events carry a `type`, `version`, `score`, and `market`, `trade`, `trader` and `inMarket` objects.

### Responses

| Status | Meaning |
| - | - |
| 2xx | Received; resending the same `webhook-id` starts no second run. |
| 400 | An empty `webhook-id`, or a body that is not JSON. |
| 401 | The signature, timestamp, provider or secret is wrong. |
| 429 or 503 | Busy or updating; retry after `Retry-After` seconds. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.