DevTune Webhooks API
Webhook subscriptions and signing secrets.
Webhook subscriptions and signing secrets.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/devtune:devtune-webhooks-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: DevTune Webhooks API
version: 2.0.0
description: API for programmatic access to your AI visibility data, webhook subscriptions, and automation workflows. Use this API to integrate DevTune data into CI/CD pipelines, BI tools, AI agents, and operational systems.
servers:
- url: https://devtune.ai/api/v2
description: Production
security:
- bearerAuth: []
tags:
- name: Webhooks
description: Webhook subscriptions and signing secrets.
paths:
/projects/{projectId}/webhooks:
get:
summary: List webhook subscriptions
description: Returns active webhook subscriptions for the project. Requires the `webhooks.read` scope.
operationId: listWebhooks
x-devtune-required-scope: webhooks.read
parameters:
- name: projectId
in: path
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Webhook subscriptions list
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
webhooks:
type: array
description: The project’s active webhook subscriptions. Signing secrets are never listed.
items:
$ref: '#/components/schemas/Webhook'
meta:
$ref: '#/components/schemas/Meta'
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
$ref: '#/components/responses/ForbiddenError'
'429':
$ref: '#/components/responses/RateLimitExceededError'
tags:
- Webhooks
post:
summary: Create a webhook subscription
description: 'Registers a new webhook subscription. Returns the subscription including the signing secret (only shown once). Each call creates a subscription, so a retry after a lost response creates a second one: list the subscriptions and delete the extra. Requires the `webhooks.write` scope.'
operationId: createWebhook
security:
- bearerAuth: []
- oauthBearer: []
x-devtune-required-scope: webhooks.write
parameters:
- name: projectId
in: path
required: true
schema:
type: string
format: uuid
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- url
- events
properties:
url:
type: string
format: uri
maxLength: 2048
description: Public HTTPS URL to POST webhook payloads to
events:
$ref: '#/components/schemas/WebhookEvents'
description: Event types to subscribe to
responses:
'201':
description: Webhook created
content:
application/json:
schema:
type: object
properties:
data:
allOf:
- $ref: '#/components/schemas/Webhook'
- type: object
properties:
secret:
type: string
description: HMAC-SHA256 signing secret. Only returned on creation.
required:
- secret
meta:
$ref: '#/components/schemas/Meta'
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
$ref: '#/components/responses/ForbiddenError'
'429':
$ref: '#/components/responses/RateLimitExceededError'
tags:
- Webhooks
/projects/{projectId}/webhooks/{webhookId}:
delete:
summary: Deactivate a webhook subscription
description: 'Deactivates a webhook subscription: it stops receiving events and leaves the list. Deactivating it again returns the same result. Requires the `webhooks.write` scope.'
operationId: deleteWebhook
security:
- bearerAuth: []
- oauthBearer: []
x-devtune-required-scope: webhooks.write
parameters:
- name: projectId
in: path
required: true
schema:
type: string
format: uuid
- name: webhookId
in: path
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Webhook deleted
content:
application/json:
schema:
type: object
properties:
deleted:
type: boolean
description: 'Always true: the subscription is off and receives no more events.'
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/NotFoundError'
'429':
$ref: '#/components/responses/RateLimitExceededError'
tags:
- Webhooks
/projects/{projectId}/webhooks/{webhookId}/rotate-secret:
post:
summary: Rotate a webhook signing secret
description: Generates a new HMAC-SHA256 signing secret for the webhook subscription. The old secret is invalidated immediately. The new secret is only returned once in this response; if you lose the response, rotate again. Requires the `webhooks.write` scope.
operationId: rotateWebhookSecret
x-devtune-required-scope: webhooks.write
parameters:
- name: projectId
in: path
required: true
schema:
type: string
format: uuid
- name: webhookId
in: path
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Secret rotated
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
secret:
type: string
description: New HMAC-SHA256 signing secret. Only returned once.
required:
- secret
meta:
$ref: '#/components/schemas/Meta'
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/NotFoundError'
'429':
$ref: '#/components/responses/RateLimitExceededError'
tags:
- Webhooks
components:
responses:
BadRequestError:
description: 'The request is invalid: a parameter or body field is missing, has the wrong type or is out of range, or a cursor doesn''t match this list. The message says which; reason, where present, is listed in the endpoint''s description. Fix the request before retrying, and restart a list without its cursor. See [Errors](/api-reference/errors).'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
UnauthorizedError:
description: 'The request has no valid credential: the Authorization header is missing or malformed, or the API key or OAuth token is invalid, expired or revoked. Send `Authorization: Bearer <API key>` with an active key, or sign in again to get a new OAuth token. See [Errors](/api-reference/errors).'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
ForbiddenError:
description: 'The credential is valid but can''t make this request. The message says which cause applies: the key or sign-in lacks the scope this endpoint requires (named in the message), it belongs to another project, the plan doesn''t include API access or this feature, the project is paused (a paused project keeps only read scopes and setup.write), or the member a write acts as no longer has the role it needs. Read `GET /projects/{projectId}/connection` for the credential''s current scopes and features, then use a key that has the scope, sign in again and approve it, or upgrade the plan. See [Errors](/api-reference/errors).'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFoundError:
description: The resource doesn't exist in this project, was deleted, or the credential can't see it. Check the IDs in the path, and that the projectId is the project the credential is bound to. See [Errors](/api-reference/errors).
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
RateLimitExceededError:
description: 'Too many requests from this credential in the current window. The request was refused before it took effect, so it is safe to retry: wait the seconds in Retry-After, then send it again. Endpoints that start agent runs have a stricter limit. See [Rate limits](/api-reference/rate-limits).'
headers:
Retry-After:
description: Seconds to wait before retrying a 429 or retryable 503 response.
schema:
type: integer
minimum: 1
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/X-RateLimit-Remaining'
X-RateLimit-Reset:
$ref: '#/components/headers/X-RateLimit-Reset'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
headers:
X-RateLimit-Limit:
description: Maximum requests per window
schema:
type: integer
X-RateLimit-Reset:
description: Unix timestamp when the window resets
schema:
type: integer
X-RateLimit-Remaining:
description: Requests remaining in current window
schema:
type: integer
schemas:
WebhookEvents:
type: array
description: The event types the subscription receives.
items:
$ref: '#/components/schemas/WebhookEventType'
minItems: 1
maxItems: 12
uniqueItems: true
Meta:
type: object
description: Sent beside data on every successful response that returns data.
properties:
timestamp:
type: string
format: date-time
description: When the response was produced.
projectId:
type: string
format: uuid
WebhookEventType:
type: string
enum:
- search-tracking.completed
- visibility.changed
- action.created
- action.updated
- action.recommendation.created
- action.recommendation.updated
- action.brief.ready
- action.draft.ready
- agent.run.completed
- outcome.measured
- traffic.sensor.stopped
- traffic.sensor.recovered
Webhook:
type: object
properties:
id:
type: string
format: uuid
description: Pass it as webhookId to delete the subscription or rotate its signing secret.
url:
type: string
format: uri
description: The URL DevTune posts events to.
events:
$ref: '#/components/schemas/WebhookEvents'
isActive:
type: boolean
description: True while the subscription receives events. Deleting a subscription turns it off, and lists return only active subscriptions.
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
description: When the subscription last changed, including a secret rotation. Absent from the create response.
Error:
type: object
properties:
error:
type: string
description: Machine-readable error code, such as bad_request, unauthorized, forbidden, not_found, conflict, payment_required, rate_limit_exceeded or internal_error. Some endpoints return their own codes, listed in their descriptions.
message:
type: string
description: What went wrong, for a person to read. Do not parse it; use error and reason.
reason:
type: string
description: Why the request was refused, for an error with more than one cause, such as a refused content-draft start.
details:
type: object
additionalProperties: true
description: Machine-readable facts about the failure or refusal, such as retryable or shortfall_credits.
properties:
retryable:
type: boolean
description: 'Read this field before retrying. Present on every 5xx and 429 response: true when another attempt may succeed, false for a permanent refusal even on a 5xx. Other refusals may also provide this field.'
retryAfterSeconds:
type: integer
minimum: 1
description: Seconds to wait when retryable is true on a 429 or 503 response, also sent in Retry-After. Uses the provider retry time or limiter reset when available; otherwise 60 seconds for 429 and GitHub throttles or 30 seconds for other 503 responses. GitHub secondary limits wait at least 60 seconds.
status:
type: integer
description: The HTTP status code, repeated in the body.
required:
- error
- message
- status
securitySchemes:
oauthBearer:
type: http
scheme: bearer
description: Project-granted OAuth access token from the authorization server advertised at /.well-known/oauth-protected-resource/api/v2. Uses the same browser consent and current project permissions as MCP. Only operations explicitly listing oauthBearer accept these tokens.
agentBearer:
type: http
scheme: bearer
description: Access token from an unclaimed agent registration (dtk_agent_ prefix), holding only setup.draft. Register at /agent/identity and exchange the identity assertion at /oauth2/token, as /auth.md describes. Only operations listing agentBearer accept it. Once a person claims the registration, its tokens act as the claimed API key under bearerAuth instead.
bearerAuth:
type: http
scheme: bearer
description: API key with dtk_live_ prefix. Obtain it from API Keys in the account sidebar. New keys start with all supported scopes selected for the chosen project, and you can narrow them to specific read/write scopes as needed.