Skip to main content
The webhooks channel lets external systems — a payments provider, a code host, an internal service — notify an agent when something happens, by calling a URL you control. An agent can have multiple webhook endpoints, typically one per third-party source. Each endpoint has its own URL, its own verification method, and its own limits.

​
Creating an endpoint

1

Name

Give the endpoint a name that identifies its source (for example, “Stripe — billing events”).
2

Verification preset

Choose how incoming requests will be verified. See Verification presets below.
3

Secret

Supply the secret used to verify incoming requests (for example, the signing secret from your provider’s dashboard, or one you generate yourself — minimum 8 characters). It’s encrypted at rest and never displayed again after creation.
4

Review

Confirm the configuration. The endpoint’s URL is generated and shown once — copy it into the third-party system’s webhook settings immediately, since it won’t be displayed again.
The endpoint URL is shown only at creation (and again after a rotation). If you lose it, you’ll need to rotate the endpoint to get a new one — the old URL stops working immediately when you do.

​
Verification presets

Pick the strongest preset your source actually supports. If it can sign requests (Stripe, GitHub, Standard Webhooks), use that — fall back to shared secret only when the source can’t sign, and avoid None outside of trusted internal systems.

​
Settings

Once created, an endpoint can be configured further:
  • Name and active/paused status — pausing stops delivery without deleting the endpoint or its history
  • Event filters — narrow which events actually reach the agent. Each filter checks a field (given as a JSON dot-path) against a value using an operator: eq, neq, in, exists, or contains. Multiple filters on the same endpoint are combined with AND. Events that don’t match are recorded but never delivered to the agent
  • Overrides — per-endpoint limits that default to the platform-wide values:
On top of each endpoint’s own quota, every agent has an aggregate cap of 1,000 events/day across all of its webhook endpoints combined.

​
Danger zone

  • Rotate token and/or secret — two independent actions. Rotating the token generates a new URL (shown once) and invalidates the old one immediately, with no overlap window; rotating only the secret keeps the URL unchanged. Use this if a URL or secret may have leaked.
  • Delete — removes the endpoint. Third-party sources still pointed at it will start receiving errors.

​
Delivery to the agent

Webhook delivery is asynchronous only — the agent never sends a synchronous HTTP response back to the calling system. The endpoint simply acknowledges receipt; the agent processes the event on its own turn. If several events arrive before the agent’s next turn, they’re batched into a single digest instead of triggering one turn per event — so a burst from a third party doesn’t flood the agent. Delivery is retried automatically so nothing gets stuck:
  • immediately, if the agent is already connected
  • when the agent reconnects
  • at the end of the agent’s current turn, if events arrived mid-turn
  • on a periodic sweep, as a safety net for anything still undelivered

​
Event log

Every event accepted by the pipeline — pending, delivered, filtered out (skipped), or quarantined — is recorded in the endpoint’s event log, filterable by status. Permanently rejected calls (invalid signature, inactive endpoint, oversized payload) don’t create log entries; they’re counted in aggregate on the endpoint. From the log you can resend an event to the agent manually, which is useful after fixing a filter or reactivating a paused endpoint.

​
What the agent sees

Only non-sensitive headers are captured and shown to the agent — headers like Authorization or Cookie are never stored, even if the source sends them. Payload content is presented to the agent as untrusted external input.

​
Security best practices

  • Prefer a signed preset (Stripe, GitHub, Standard Webhooks) over shared secret or none whenever the source supports it.
  • Rotate secrets periodically, and immediately if you suspect a leak.
  • Use event filters to keep the agent focused on events that actually matter, reducing noise and quota usage.
  • Give each third-party source its own endpoint rather than sharing one — it keeps verification, filters, and quotas isolated per source.

​
See also

  • Channels overview — principles shared across all channels
  • Email — for unstructured, human-originated messages instead of system events
  • Activity — every delivered webhook event appears in the timeline tagged with the webhook badge