DevTune Webhooks API

Webhook subscriptions and signing secrets.

GitHub OpenAPI

Operations 4

GET /projects/{projectId}/webhooks List webhook subscriptions #
POST /projects/{projectId}/webhooks Create a webhook subscription #
DELETE /projects/{projectId}/webhooks/{webhookId} Deactivate a webhook subscription #
POST /projects/{projectId}/webhooks/{webhookId}/rotate-secret Rotate a webhook signing secret #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • 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.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/devtune:devtune-webhooks-api"
All apis
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.

Get an API 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 Specification

devtune-webhooks-api-openapi.yml Raw ↑
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.