Browse documentation

Wake an agent from incoming events

beta

Connect GitHub, Grafana, or another service to wake an agent from incoming events. Set up authentication, choose event filters, and check delivery results.

An event trigger gives an agent a task when another service sends an event. GitHub offers PR merged and Release published presets. Grafana offers alert notifications with firing, resolved, and label filters. Other services can use Generic webhook. Results appear in the agent's existing conversation. The agent keeps its configured permissions, approval rules, model policy, and daily budget.

If you see Webhooks in the agent settings, you can configure incoming events for this agent.

Who can set this up

Source setup requires permission to manage workspace connectors. Trigger changes require a workspace administrator who can edit the agent. You also need permission to configure webhooks on the GitHub repository.

A repository event does not grant access to repository contents. Connect an appropriate GitHub account separately if the agent needs to inspect private code or checks.

Event work applies the stricter no-training preferences of the trigger creator and the agent owner, together with organization requirements. A repository event cannot relax those choices.

Event-triggered work can use the agent's usual tools and connected services. AWS and Kubernetes still require their existing access grants. The event does not grant additional access. The trigger creator must retain permission to manage the agent; losing that permission stops new event work and further protected reads.

The agent can leave questions, approval requests, and access proposals in its conversation for you to answer. Approved actions can resume the task. Review cards for email sends, calendar events, and other protected actions still apply. A webhook does not require you to be online when work starts.

Ask the agent about its webhooks

Ask the agent to inspect its existing webhooks. The agent can list permitted sources and saved triggers. It cannot create or change a trigger. To add a trigger, use the agent's settings.

Create an event trigger

Open the agent's settings and select Webhooks. Select Sources, then Add source to connect a service. Sources are shared within the workspace. Select New trigger, choose a source, and write the instructions the agent should follow.

Budget and pause apply at once; each trigger has its own Save. Existing triggers keep their source and event preset. Create another trigger to change either.

Webhook secrets appear only in source setup. Show or copy the secret there, save it with your sender, and confirm that you saved it before closing. Never send it to the agent. If source creation loses its reply, check the source list before creating another source. A generic source's lost secret cannot be retrieved; configure a new source and disable the unused one. A GitHub source can use Install webhook with an authorized connection. A Grafana bearer source can create its contact point through an authorized connection.

Connect GitHub

  1. Open Sources → Add source and select GitHub.
  2. Select an existing GitHub connection, or select Connect GitHub and complete authorization.
  3. Choose a repository where your connection has administration access.
  4. Select Create source and save the signing secret securely.
  5. Select Install GitHub webhook.
  6. Confirm I saved the secret securely, then select Done.
  7. Open Sources, expand the source, and select Check verification after GitHub sends its verification ping.

For manual setup, enter the repository as owner/repository and create the source. Copy its URL and signing secret into GitHub's repository Settings → Webhooks → Add webhook. Choose application/json, enable Pull requests and Releases, and keep SSL verification on.

Create a trigger using PR merged or Release published. A PR trigger can match a Base branch. Release triggers exclude prereleases unless you select Include prereleases. Closing an unmerged PR, creating a draft release, or editing a release does not match these presets.

Connect Grafana

  1. Open Sources → Add source and select Grafana.
  2. Enter a source name and your Grafana HTTPS origin, such as https://grafana.example.com.
  3. Keep Bearer token for Grafana 11.1 compatibility, then select Create source.
  4. In Grafana, open Alerting → Contact points → Add contact point and select the Webhook integration.
  5. Copy the displayed URL and use POST. Set the Authorization header scheme to Bearer and its credentials to the displayed token.
  6. Save the contact point and select Test in Grafana. In d5s, select Check verification.
  7. Confirm that Grafana reached d5s. Save a trigger with your desired status, exact-label filters, and agent instructions.
  8. Select Start delivering when you are ready. In Grafana, route the desired alerts to this contact point.

If a Grafana connection for the same host is available, you can create the contact point from source setup. The connection needs alerting write permission. This action creates only the contact point; it does not change notification policies. If access is denied, use manual setup. If the reply is lost, retry to check for the existing contact point.

New Grafana sources start in Test mode. All accepted requests, including real alerts, are recorded without waking agents. Test mode stays on until you select Start delivering. Use Return to test mode before sending more setup tests. A payload named TestAlert is ordinary event data; it does not control test mode.

Choose firing alerts, resolved alerts, or both. Label filters use exact key and value matches on the same alert. For example, severity=critical and namespace=production must both match one alert. A grouped notification starts one task per matching trigger. The card shows which alerts matched and any alerts omitted by Grafana. Keep resolved notifications enabled in Grafana if the trigger watches resolved alerts.

Grafana notifications can be at most 256 KiB and contain at most 200 alerts. Set Max Alerts to 200 or less. Without a stable delivery ID, identical Grafana notifications received within five minutes are treated as retries. An identical notification received later can start another task. A sender that supplies X-Webhook-Id must keep the same ID for retries and use a new ID for a new notification.

With HMAC and no timestamp, an identical signed body is treated as a replay even after five minutes. Configure signed timestamps for repeated notifications with identical content. A verification request does not prevent the same notification from starting a task after you select Start delivering.

For Grafana versions that offer HMAC signing, select HMAC-SHA256 and use the displayed secret. Send the raw hexadecimal SHA-256 signature in X-Grafana-Alerting-Signature. If you configure a timestamp, use X-Grafana-Alerting-Timestamp and sign timestamp + ":" + raw request body. The timestamp must be within five minutes. This format differs from the generic webhook signature. Grafana 11.1 uses bearer setup.

Source setup does not grant the agent Grafana or Kubernetes access. Connect the tools the agent needs separately. Grafana links in event cards must match the configured Grafana origin.

Connect another service

  1. Open Sources → Add source. Generic webhook is selected by default.
  2. Enter a Source name and select Authentication.
  3. Select Create source and save the secret securely.
  4. Configure your service to send a JSON object to the displayed webhook URL. Confirm I saved the secret securely, then select Done.
  5. Create a trigger for that source and send a test event from your service.

With Bearer token, send Authorization: Bearer <token>. With HMAC-SHA256, send X-Webhook-Signature: sha256=<hex digest>. Calculate that digest over the exact request body using the signing secret. The secret is shown once, when you create the source.

An optional Event name filter selects events by name. Bearer authentication uses X-Webhook-Event, then the JSON event field, or type when event is absent. HMAC authentication uses the signed JSON event or type field. A conflicting header is rejected. Leave the filter empty to accept any event from the source.

For example, a build service can send:

{
  "event": "build.failed",
  "title": "Build 123 failed",
  "url": "https://builds.example.com/runs/123",
  "result": "failed"
}

Use an Event name of build.failed and instructions such as "Inspect this build failure and propose a fix."

Send a stable X-Webhook-Id when retrying the same event. A retry with the same ID and content does not create another agent delivery. Reusing that ID for different content returns 409. With bearer authentication, each request without this header is a new event. HMAC authentication also rejects replay of an identical signed body, even with another header ID. Include a unique event ID or timestamp inside the JSON body when separate HMAC events otherwise have identical content.

Generic payloads can be at most 2 MiB. The agent receives the first 32,000 characters of a larger payload. Each source accepts at most 120 new requests per minute. A 429 response includes a Retry-After header. Retry the same event ID after that delay.

Your sender must support the selected authentication headers. If it cannot, use an adapter that authenticates and forwards its events. Native provider signature formats other than GitHub's are not supported by the generic HMAC option.

Webhook setup lets a service send events. Connect its tools separately if the agent needs to read data or take actions there. Do not include credentials in payloads or trigger instructions.

Check the result

Incoming events appear as compact event cards in the conversation. They show the event, source, title, and relevant commit, release tag, or grouped Grafana alert status. Expand Details to inspect the saved instructions and received event data. These cards identify the event as the sender.

A successful webhook response confirms receipt of the event; it does not confirm that the agent finished its task. Delivery history distinguishes waiting work, work sent to the agent, completion, failure, and skipped events. Open the agent conversation to review the result and any approval requests.

Disabled sources or triggers stop new event work. Paused, inactive, or budget-limited agents skip matching deliveries. These skipped events do not automatically run when you resume the agent. You can ask the agent to inspect the relevant PR or release directly.

Changing instructions applies to future events. A received event keeps the instructions saved when it arrived. Disabling a trigger stops new event work from reaching the agent. Disabling a source or trigger also stops events that have not started. Work already running can continue.

When workspace deletion starts, d5s stops accepting new events. Pending deliveries do not start agent work.

If a delivery fails

Open Sources, expand the source, and select Request history to inspect authenticated requests. A Filtered request did not match an enabled trigger. Its reason can identify an event-name mismatch, branch mismatch, excluded prerelease, or Grafana status and label mismatch. Test-mode requests state that no agent was woken.

If no request appears, check the sender’s delivery log, webhook URL, authentication, JSON format, and source enabled state. For GitHub, also check the exact repository and selected webhook events.

For a skipped or failed agent task, check the agent's pause state, enabled trigger, daily budget, credits, and model availability. Review the conversation before asking the agent to run the task again.

Last reviewed
No results yet

Try a product noun such as agent, project, or connector.