Event Types
action.* events track the action entity lifecycle. action.recommendation.* events track the recommendation surface. Recommendation update events are intentionally quiet: they do not fire for recommendation reorder, acceptance, small citation drift, evidence reorder, wording-only changes, or brief absence alone.
action.status is suggested, accepted, live or archived, the same values the actions API returns. action.blocked is true on accepted work your team has marked blocked. A suggestion DevTune withdraws before anyone acts on it sends no further events.
Managing Webhooks via the Dashboard
You can create and manage webhooks directly from your account settings in the DevTune dashboard.- Navigate to your team account
- Open Webhooks in the account sidebar
- Click Create Webhook
- Fill in the form:
- Endpoint URL — The HTTPS URL that will receive webhook POST requests
- Project — Select which project’s events should trigger the webhook
- Events — Check one or more event types to subscribe to
- Click Create Webhook
- Copy the signing secret shown in the dialog — this is the only time it will be displayed
- If you ever need a new secret, click the rotate icon next to the webhook — this generates a new secret and invalidates the old one immediately
Note: The Webhooks page requires the Plus plan or above (API Access entitlement). You must also be an Admin on the project.
Managing Webhooks via the API
The REST API and native MCP use the same project-bound webhook operations. Listing returns active subscriptions without signing secrets. Creation and rotation return a signing secret once. Store it securely; it cannot be retrieved later. Rotation invalidates the previous secret immediately, so update your receiver with the replacement. Destinations must be public HTTPS URLs. Validation checks DNS and rejects internal, private, loopback and reserved addresses, including a hostname that resolves to both public and private addresses. Subscribe to one or more unique events from the event table above. Webhook IDs must be UUIDs; invalid IDs return400. Unknown subscriptions and subscriptions outside the credential’s account or project return 404. Rotation also returns 404 for inactive subscriptions. Deleting an already inactive subscription still returns {"deleted":true}. A server error returns 500. If DevTune cannot read the complete list of subscriptions, listing returns 500 rather than a partial list. Operations are not automatically retried; after an uncertain create or rotation outcome, inspect the subscriptions before deciding whether to repeat the operation.
Managing webhooks via native MCP
The connection selects the project; these tools do not accept account or project overrides. API keys need the matching scopes. OAuth connections need consent for webhook scopes on the selected project, and the person who connected must be a project Admin. An API key acts as its creator, so a key whose creator is no longer an Admin can’t manage webhooks. To add webhook access to an existing connection, revoke the client’s OAuth authorization and connect again. Webhooks need the API Access entitlement (Plus plan or above).
Activity logs record operation metadata, without tool arguments, signing secrets or response bodies.
MCP code mode also offers these operations; writes need
webhooks.write and an approved execution. A signing secret returned in code mode is delivered only in the original response and is not saved for replay. See Code mode operations.
REST examples
Scoped API keys must include:webhooks.readto list webhook subscriptionswebhooks.writeto create, delete, or rotate webhook secrets
Create a Webhook
Response (201)
webhooks.write gets 403; see Error handling.
List Webhooks
Response (200)
Delete a Webhook
Response (200)
Rotate Webhook Secret
Response (200)
Webhook Payload Format
When an event fires, DevTune sends a POST request with this body:timestamp is when this delivery attempt was sent. For search-tracking.completed, finalStatus is completed, or partial when the run finished with some prompts failing. A run that fails sends no event.
visibility.changed payload
previousMetrics is null when there is no prior data (e.g., the first run for a project).
action.created payload
action.updated payload
action.recommendation.created payload
recommendationContext.opportunity carries the same percentile, percentilePoolSize, components, estimated, family and measuredFacts fields the actions API returns. action.portfolioRank is its position in the project’s queue: lower comes first, and null sorts last.
Read percentile with percentilePoolSize, the number of ranked opportunities of the same type. A pool size of one means it is the only ranked opportunity of its type, not the top 1%; when the pool size is missing, don’t read a percentile of 100 as the only one. Citation-defence recommendations also carry the window date, current and prior citation counts, and probe-day coverage in measurements. Accepted and live actions omit opportunity, because only suggestions are re-ranked.
Values in action payloads
action.recommendation.updated payload
action.recommendation.updated uses the same payload shape as action.recommendation.created, with recommendationContext.changeReasons explaining why review is recommended.
GET /api/v2/projects/{projectId}/actions/list?detailLevel=contextGET /api/v2/projects/{projectId}/actions/{actionId}/briefGET /api/v2/projects/{projectId}/actions/{actionId}/eventsfor who changed an action and what they changed- MCP
devtune_get_actionswithdetailLevel: "context" - MCP
devtune_get_action_brief - MCP
devtune_get_action_events
action.brief.ready payload
Sent when a brief you started (from the app, the API or MCP) is ready, or when its generation fails. status is completed or failed. A brief that fails and is then generated again sends a second event.
action.draft.ready payload
Sent when a content draft run for an action ends. status is completed when the draft is ready for your review (draftAwaitingReview: true), failed, blocked or canceled. Read the draft from links.apiActionDraft; DevTune never publishes it.
reason says why a blocked or canceled run stopped: credits_exhausted, evidence_unavailable, project_paused or conversation_expired. It is null for other statuses, and for a run stopped without one of those reasons.
agent.run.completed payload
Sent when an agent run ends, for the runs GET /api/v2/projects/{projectId}/agents/runs lists: your project’s agents and custom agents, whether you started the run or it ran on its schedule. Other agent work, such as a conversation with DevTune in Slack, sends nothing. status is completed when the run produced a draft for your review (draftAwaitingReview: true), failed, blocked or canceled. Content draft runs send action.draft.ready instead.
reason says why a blocked or canceled run stopped: credits_exhausted, evidence_unavailable, project_paused or conversation_expired. It is null for other statuses, and for a run stopped without one of those reasons.
outcome.measured payload
Sent when a shipped action’s before/after result is measured as improved, mixed, no_clear_change or declined, and again whenever that result changes. Measurements that are still running or unmeasured send nothing. DevTune checks results that reached the Results ledger in the last 30 days once an hour, so an event usually arrives within about an hour of the result appearing there, and a result that reached the ledger more than 30 days ago is never sent. Results that reached the ledger before you subscribed are not sent. Editing the webhook before its first hourly check moves that start to the edit. Turning the webhook off and on again within the same hour keeps the earlier start; after a longer gap, results from the gap are not sent.
result is the ledger’s result for the measurement, never an estimate. links.apiOutcomesLedger returns the Results ledger for actions completed in the last 365 days, with the comparison windows for this measurement in overlappingActions; page through items to the row whose interventionId matches. measurementOpenedAt is when the action went live, windowClosedAt when its comparison window closed and measuredAt when the result was decided. method is v1 or v2 for a closed window, and null otherwise.
traffic.sensor.stopped and traffic.sensor.recovered payloads
Sent when an AI Traffic sensor’s status in GET /api/v2/projects/{projectId}/traffic/sensors crosses between reporting and stopped. traffic.sensor.stopped is sent when it changes from active to stale, needs_reconnect or error; traffic.sensor.recovered when it reads active again. A move between stale, needs_reconnect and error sends nothing. Any other status, such as configured, paused or not_connected, sends nothing and leaves the sensor’s last state as it was, so a sensor that stopped and was then reconnected sends traffic.sensor.recovered once it reads active. Disconnecting or pausing a connection, or pausing the project, sends nothing, except that one traffic.sensor.stopped can still arrive if the change lands while DevTune is checking that sensor.
DevTune checks each sensor once an hour, so an event usually arrives within about an hour of the status changing. Once a sensor has accepted data, Cloudflare, Search Console and GA4 read stale when their last sync failed, or after 2, 22 and 46 hours without a sync. The Vercel log drain stops only on error or needs_reconnect. The tracking snippet and edge middleware never read stale, because a site with no AI traffic and a snippet that stopped look the same, so they send neither event.
DevTune keeps each sensor’s last state per project, not per webhook. Each hourly check clears it for a project that is paused or has no active webhook subscribed to either event. The first check after that, or after the project’s first such subscription, records each sensor’s status and sends nothing; a sensor already stopped then sends traffic.sensor.recovered when it reports again. Sensors the read doesn’t return on your plan send nothing.
sensor is the sensor’s id in the sensors read: cloudflare, vercel_drain, search_console or ga4. status and lastSeenAt are what the read returned at the check. connectionIds lists the ids of the Cloudflare, Search Console or GA4 connections the read returned for the sensor, and is null for the Vercel drain.
Headers
Verifying Signatures
Every webhook delivery includes anX-DevTune-Signature header containing an HMAC-SHA256 hex digest computed with your webhook secret.
Node.js Example
Important: Use the raw request body (before JSON parsing) for signature verification. In Express, use express.raw({ type: 'application/json' }) on your webhook route to get the raw buffer.
Python Example
Retry Policy
A delivery succeeds when your endpoint returns a 2xx status within 10 seconds. Anything else fails: another status, a connection error, or no complete response within 10 seconds. Redirects are not followed, so a 3xx also fails. DevTune retries a failed delivery up to 3 times with exponential backoff, so each event gets at most 4 attempts. After the last attempt the event is not sent again. Deleting the webhook stops any retries still pending. A410 response deletes the webhook without a retry; create it again to resume deliveries. The dashboard doesn’t show delivery attempts, so log incoming requests on your endpoint if you need to debug deliveries.
Build your receiver for repeats and reordering:
- Respond fast. Verify the signature, store the event, return a 2xx, then process it. Work that runs past 10 seconds fails the attempt and causes a retry.
- Expect duplicates. A retry can repeat an event you already processed, for example when your endpoint did the work but answered too late. A repeat carries the same
eventanddatawith a newtimestampand signature, so compareeventanddatato spot one. Forsearch-tracking.completedandvisibility.changed,eventplusdata.runIdis enough.action.brief.ready,action.draft.ready,agent.run.completed,outcome.measured,traffic.sensor.stoppedandtraffic.sensor.recoveredcarrydata.eventId, the same on every send of one event. - Don’t rely on order. Events are delivered independently, and a retried event can arrive after a newer one. Read the current state from the API before acting on an older event.
Use Cases
- Slack notifications when a tracking run finishes
- CI/CD triggers to re-run checks when visibility changes
- Data pipelines that sync DevTune data to your warehouse on each update
- GTM automation that feeds generated actions into triage systems or agentic workflows
Related Endpoints
- Authentication - API key creation and usage
- Error Handling - Error codes and troubleshooting