openapi: 3.0.3
info:
  title: naturali.ai — Webhooks API
  version: 1.0.0
  description: >
    Webhooks and events, scoped to a project. Register an HTTPS
    endpoint, subscribe it to the event types you care about, and naturali POSTs
    a signed JSON envelope to it whenever one of them happens — so an
    integration reacts to a card moving or a message arriving instead of polling
    for it.

    **Every delivery is recorded.** A `WebhookDelivery` row is committed before
    any request is attempted, which is what makes retries and the
    `…:redeliver` action possible: the event survives a receiver being down, and
    it survives naturali restarting mid-flight. Deliveries are readable per
    project, so "did that event reach us, and what did our endpoint say" is a
    question the API answers. A settled delivery is kept for 30 days.

    **Every delivery is signed.** `X-Naturali-Signature` carries a timestamped
    HMAC-SHA256 over the request body — verify it before acting on a payload,
    and reject timestamps outside a window you choose. The signing secret is
    returned exactly once, when the webhook is created and again when it is
    rotated; there is no endpoint that reads it back.
  contact:
    name: naturali.ai
    url: https://naturali.ai
servers:
  - url: '{baseUrl}'
    description: Host of your naturali.ai deployment; every path carries the /v1 prefix.
    variables:
      baseUrl:
        description: Base host URL.
        default: https://api.naturali.ai
tags:
  - name: Webhooks
    description: Subscribe an endpoint to a project's events, and audit what was delivered.
security:
  - bearerAuth: []
  - oauth2:
      - mcp:access
paths:
  /v1/projects/{project_id}/webhooks:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    get:
      tags: [Webhooks]
      summary: List webhooks
      description: The endpoints registered in the project, newest first.
      operationId: listWebhooks
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Cursor'
      responses:
        '200':
          description: A page of webhooks.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Page'
                  - properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/Webhook'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      tags: [Webhooks]
      summary: Create a webhook
      description: >
        Register an endpoint and subscribe it to one or more event types.

        The response carries `secret` — the signing key, in plaintext. **This is
        the only time it is returned.** Store it where your receiver can read
        it; if you lose it, rotate rather than re-create, so the endpoint keeps
        its delivery history. Send `secret` yourself to sign with a key your
        receiver already holds; the response then returns that one.

        A project holds at most 20 webhooks, inactive ones included; the 21st
        is refused with `409 WEBHOOK_LIMIT_REACHED`.

        Returns `501` on a deployment with no credential-sealing key configured,
        since the secret could not then be stored safely.
      operationId: createWebhook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookCreate'
      responses:
        '201':
          description: Webhook created. The signing secret is included, once.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookWithSecret'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/WebhookLimitReached'
        '501':
          $ref: '#/components/responses/SealingKeyNotConfigured'
  /v1/projects/{project_id}/webhooks/{webhook_id}:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/WebhookId'
    get:
      tags: [Webhooks]
      summary: Get a webhook
      description: >
        The endpoint, the events it is subscribed to and whether deliveries are
        attempted. The signing secret is not returned: it is shown once by
        [`POST /v1/projects/{project_id}/webhooks`](/docs/api/webhooks/create-webhook)
        and again by
        [`POST /v1/projects/{project_id}/webhooks/{webhook_id}:rotate-secret`](/docs/api/webhooks/rotate-webhook-secret).
      operationId: getWebhook
      responses:
        '200':
          description: The webhook.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      tags: [Webhooks]
      summary: Update a webhook
      description: >
        Change the destination, the subscription, the label, the signing secret
        or whether deliveries are attempted at all. At least one field is
        required. A `secret` sent here is never returned.

        Setting `active: false` is the reversible half of `DELETE`: deliveries
        stop, the endpoint and its history stay. It is what to reach for while a
        receiver is being repaired.
      operationId: updateWebhook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookUpdate'
      responses:
        '200':
          description: Webhook updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags: [Webhooks]
      summary: Delete a webhook
      description: >
        Removes the endpoint and its delivery records. To stop deliveries while
        keeping the audit trail, `PATCH` it to `active: false` instead.
      operationId: deleteWebhook
      responses:
        '204':
          description: Webhook deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  '/v1/projects/{project_id}/webhooks/{webhook_id}:rotate-secret':
    parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/WebhookId'
    post:
      tags: [Webhooks]
      summary: Rotate the signing secret
      description: >
        Issues a new signing secret for the same endpoint and returns it — the
        second and last time a secret is ever returned. This is the `…:rotate-secret`
        action; the path segment is `{webhook_id}:rotate-secret`.

        The change takes effect on the next delivery, including retries of
        deliveries already queued, so roll the new secret out to your receiver
        promptly. There is no overlap window in which both secrets verify.
      operationId: rotateWebhookSecret
      responses:
        '200':
          description: A new signing secret was issued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookWithSecret'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '501':
          $ref: '#/components/responses/SealingKeyNotConfigured'
  /v1/projects/{project_id}/webhook-deliveries:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    get:
      tags: [Webhooks]
      summary: List webhook deliveries
      description: >
        Every delivery attempted in the project, newest first — what was sent,
        where, how many times, and what came back. Filter by endpoint, by
        lifecycle status, or by event type.

        Deliveries are per (event, endpoint): an event matching two subscribed
        endpoints produces two rows, retried and observed independently.

        A `success` or `failed` delivery is deleted 30 days after it was
        created, and can no longer be read or redelivered. A `pending` one is
        kept until it settles.
      operationId: listWebhookDeliveries
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Cursor'
        - name: webhook_id
          in: query
          required: false
          description: Only deliveries addressed to this endpoint.
          schema:
            type: string
            example: whk_V1StGXR8Z5jdHi6B
        - name: status
          in: query
          required: false
          description: Only deliveries in this state.
          schema:
            type: string
            enum: [pending, success, failed]
        - name: type
          in: query
          required: false
          description: Only deliveries of this event type.
          schema:
            type: string
            example: generations.completed
      responses:
        '200':
          description: A page of deliveries.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Page'
                  - properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/WebhookDelivery'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/projects/{project_id}/webhook-deliveries/{delivery_id}:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/DeliveryId'
    get:
      tags: [Webhooks]
      summary: Get a webhook delivery
      description: >
        One delivery, including the exact payload that was signed and sent.
      operationId: getWebhookDelivery
      responses:
        '200':
          description: The delivery.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookDelivery'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  '/v1/projects/{project_id}/webhook-deliveries/{delivery_id}:redeliver':
    parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/DeliveryId'
    post:
      tags: [Webhooks]
      summary: Redeliver an event
      description: >
        Queue the same event at the same endpoint again — the recovery path for
        a delivery that failed, or one your receiver dropped. This is the
        `…:redeliver` action; the path segment is `{delivery_id}:redeliver`.

        A **new** delivery is created and returned; the original record is left
        untouched, because its attempt history is the evidence you redelivered
        on. The event's `id` is carried over unchanged, so a receiver deduping
        on the event sees the same event twice while one deduping on
        `X-Naturali-Delivery` sees a distinct delivery.

        An inactive webhook is refused with `409 WEBHOOK_INACTIVE`.
      operationId: redeliverWebhookDelivery
      responses:
        '202':
          description: A new delivery was queued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookDelivery'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/WebhookInactive'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: A naturali API key (nat_sk_…) or a session JWT.
    oauth2:
      type: oauth2
      description: >-
        A connected app's OAuth access token, issued by this API's authorization
        server (discovery: /.well-known/oauth-authorization-server). Its one scope
        carries every operation, confined to the projects the user chose when
        approving the app.
      flows:
        authorizationCode:
          authorizationUrl: https://api.naturali.ai/authorize
          tokenUrl: https://api.naturali.ai/token
          refreshUrl: https://api.naturali.ai/token
          scopes:
            mcp:access: Every operation this API serves, on the projects the grant covers.
  parameters:
    Limit:
      name: limit
      in: query
      required: false
      description: >-
        Results per page, 1 to 100 (default 50). Above 100 it is clamped; below 1
        or not an integer it is `400`.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 50
    Cursor:
      name: cursor
      in: query
      required: false
      description: >-
        The previous page's `next_cursor`; omit it for the first page. A cursor
        this list did not issue is `400`.
      schema:
        type: string
    ProjectId:
      name: project_id
      in: path
      required: true
      description: Project public ID (proj_ prefix).
      schema:
        type: string
        example: proj_V1StGXR8Z5jdHi6B
    WebhookId:
      name: webhook_id
      in: path
      required: true
      description: Webhook public ID (whk_ prefix).
      schema:
        type: string
        example: whk_V1StGXR8Z5jdHi6B
    DeliveryId:
      name: delivery_id
      in: path
      required: true
      description: Delivery public ID (whd_ prefix).
      schema:
        type: string
        example: whd_V1StGXR8Z5jdHi6B
  responses:
    Forbidden:
      description: >-
        The credential is scoped to a different project, or the caller's role in
        the project does not carry this action.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Missing or invalid credentials.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: The request was malformed or failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: The resource does not exist (existence is not leaked).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    WebhookLimitReached:
      description: >
        The project already holds 20 webhooks (`WEBHOOK_LIMIT_REACHED`);
        `meta.limit` carries the ceiling.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    WebhookInactive:
      description: >
        The delivery's webhook is inactive (`WEBHOOK_INACTIVE`).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    SealingKeyNotConfigured:
      description: >
        The requested path is not enabled on this deployment — a webhook secret
        cannot be stored where no credential-sealing key is configured.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    Page:
      type: object
      description:
        One page of a list. Rows inserted or removed between two calls neither repeat nor skip
        a row on the next page.
      required:
        - data
        - next_cursor
      properties:
        data:
          type: array
          description: This page's items, in the list's order.
          items: {}
        next_cursor:
          type: string
          nullable: true
          description: Pass as `cursor` to fetch the next page; `null` on the last page.
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          description: >-
            Structured error. Every error response uses this shape, so `code` can
            be read without first checking the type of `error`.
          required:
            - code
            - message
            - hint
          properties:
            code:
              type: string
              pattern: '^[A-Z][A-Z0-9_]*$'
              description: >-
                Machine-readable error code, UPPER_SNAKE whether naturali or the
                runtime raises it.
              example: FORBIDDEN
            message:
              type: string
              description: Human-readable explanation.
              example: Your role in this project does not carry this action.
            hint:
              type: string
              description: >-
                What to do about it, naming the routes of this API to call. For
                people and agents; it may change, so branch on `code`.
              example: >-
                Use a credential whose scope includes this action, or ask a
                project `admin` or `owner` to act; the caller's role or key
                excludes it.
            meta:
              type: object
              additionalProperties: true
              description: >-
                Structured context, such as the `resource` and `limit` of a
                `PLAN_LIMIT_REACHED`.
    EventType:
      type: string
      description: >
        A naturali event type. Its values are what this API emits —
        deliberately only the events it can itself cause, so no declared name is
        one that never fires. It grows as modules land.
      enum:
        - conversations.started
        - messages.received
        - generations.completed
        - generations.failed
        - usage_thresholds.crossed
        - projects.paused
        - projects.resumed
        - decisions.completed
        - decisions.failed
        - tasks.created
        - tasks.transitioned
        - tasks.closed
        - tasks.migrated
        - tasks.stalled
        - tasks.paused
        - tasks.resumed
        - tasks.approval_failed
        - tasks.automation_retrying
        - tasks.automation_rejected
        - tasks.automation_unrouted
        - tasks.unblocked
        - approvals.created
        - approvals.approved
        - approvals.rejected
        - approvals.expired
        - exceptions.created
      example: conversations.started
    EventSubscription:
      type: array
      minItems: 1
      description: >
        Which events this endpoint receives. Each entry is an exact type
        (`generations.completed`), a resource wildcard (`generations.*`), or `*`
        for everything. A bare resource name (`generation`) matches nothing and
        is rejected.
      items:
        type: string
      example: [generations.*, messages.received]
    Event:
      type: object
      description: >
        The envelope POSTed to your endpoint. It is also what a delivery's
        `payload` holds, byte for byte, so the signed body and the recorded one
        are the same document.
      required:
        [id, type, project_id, resource_type, resource_id, data, created_at]
      properties:
        id:
          type: string
          description: >
            Unique per event (`evt_` prefix), and stable across redeliveries —
            dedupe on this if your receiver must process an event exactly once.
          example: evt_V1StGXR8Z5jdHi6B
        type:
          $ref: '#/components/schemas/EventType'
        project_id:
          type: string
          x-naturali-ref: project
          example: proj_V1StGXR8Z5jdHi6B
        resource_type:
          type: string
          description: What the event is about.
          enum:
            [
              conversation,
              message,
              generation,
              usage_threshold,
              project,
              decision,
              task,
              approval,
              exception,
            ]
          example: conversation
        resource_id:
          type: string
          description: The id of that resource, in the form its own API uses.
          example: conv_V1StGXR8Z5jdHi6B
        data:
          type: object
          additionalProperties: true
          description: >
            The resource, shaped exactly as its own API returns it — a
            `generations.completed` payload carries the same object
            `getGeneration` would.
        created_at:
          type: string
          format: date-time
          example: '2026-07-31T00:00:00.000Z'
    Webhook:
      type: object
      required:
        [
          id,
          project_id,
          url,
          events,
          description,
          active,
          created_at,
          updated_at,
        ]
      properties:
        id:
          type: string
          description: Public webhook ID (whk_ prefix).
          example: whk_V1StGXR8Z5jdHi6B
        project_id:
          type: string
          description: "The owning project."
          x-naturali-ref: project
          example: proj_V1StGXR8Z5jdHi6B
        url:
          type: string
          format: uri
          description: >-
            Where deliveries are POSTed: an `https://` URL on a public internet
            host. A host that is, or resolves to, a loopback, private or
            link-local address is refused, at save and at each delivery;
            redirects are not followed.
          example: https://example.com/hooks/naturali
        events:
          $ref: '#/components/schemas/EventSubscription'
        description:
          type: string
          nullable: true
          description: Operator-facing label.
          example: billing service
        active:
          type: boolean
          description: Whether deliveries are attempted.
          example: true
        created_at:
          type: string
          format: date-time
          example: '2026-07-31T00:00:00.000Z'
        updated_at:
          type: string
          format: date-time
          example: '2026-07-31T00:00:00.000Z'
    WebhookWithSecret:
      allOf:
        - $ref: '#/components/schemas/Webhook'
        - type: object
          required: [secret]
          properties:
            secret:
              type: string
              description: >
                The signing key, returned only by create and rotate. A generated
                one carries the `whsec_` prefix; a chosen one is returned as
                sent. Never readable afterwards.
              example: whsec_V1StGXR8Z5jdHi6BQe4kL2mN
    WebhookCreate:
      type: object
      required: [url, events]
      properties:
        url:
          type: string
          format: uri
          description: >
            An `https://` endpoint on a public internet host. A host that is,
            or resolves to, a loopback, private or link-local address is
            refused, here and again at each delivery; redirects are not
            followed.
          example: https://example.com/hooks/naturali
        events:
          $ref: '#/components/schemas/EventSubscription'
        description:
          type: string
          nullable: true
          example: billing service
        active:
          type: boolean
          default: true
          example: true
        secret:
          $ref: '#/components/schemas/WebhookSecret'
    WebhookSecret:
      type: string
      minLength: 32
      maxLength: 256
      pattern: '^\S+$'
      description: >
        A signing key of your choosing, 32 to 256 characters with no
        whitespace. Omit it on create to have one generated.
      example: my-receiver-signing-key-0123456789ab
    WebhookUpdate:
      type: object
      description: At least one field is required.
      properties:
        url:
          type: string
          format: uri
          example: https://example.com/hooks/naturali-v2
        events:
          $ref: '#/components/schemas/EventSubscription'
        description:
          type: string
          nullable: true
          example: billing service (staging)
        active:
          type: boolean
          example: false
        secret:
          $ref: '#/components/schemas/WebhookSecret'
    WebhookDelivery:
      type: object
      description: One event addressed to one endpoint, and everything that happened to it.
      required:
        - id
        - project_id
        - webhook_id
        - event_id
        - type
        - payload
        - status
        - status_code
        - attempts
        - next_attempt_at
        - last_attempt_at
        - response_body
        - created_at
        - updated_at
      properties:
        id:
          type: string
          description: >
            Public delivery ID (whd_ prefix). Sent with the request as
            `X-Naturali-Delivery`.
          example: whd_V1StGXR8Z5jdHi6B
        project_id:
          type: string
          description: "The owning project."
          x-naturali-ref: project
          example: proj_V1StGXR8Z5jdHi6B
        webhook_id:
          type: string
          description: "The endpoint the delivery is addressed to."
          x-naturali-ref: webhook
          example: whk_V1StGXR8Z5jdHi6B
        event_id:
          type: string
          description: The event's id; shared by every delivery and redelivery of it.
          example: evt_V1StGXR8Z5jdHi6B
        type:
          $ref: '#/components/schemas/EventType'
        payload:
          $ref: '#/components/schemas/Event'
        status:
          type: string
          enum: [pending, success, failed]
          description: >
            `pending` until a 2xx is received (`success`) or the attempts are
            exhausted (`failed`). A failed delivery can be replayed with
            `…:redeliver`.
          example: success
        status_code:
          type: integer
          nullable: true
          description: >
            The receiver's HTTP status on the last attempt; null when the
            attempt never got a response (DNS, TLS, refused, timed out).
          example: 200
        attempts:
          type: integer
          description: Attempts made so far.
          example: 1
        next_attempt_at:
          type: string
          format: date-time
          nullable: true
          description: When the next retry is due; null once the delivery is terminal.
          example: null
        last_attempt_at:
          type: string
          format: date-time
          nullable: true
          example: '2026-07-31T00:00:01.000Z'
        response_body:
          type: string
          nullable: true
          description: >
            A truncated snippet of the receiver's response, or the transport
            error when there was no response.
          example: ok
        created_at:
          type: string
          format: date-time
          example: '2026-07-31T00:00:00.000Z'
        updated_at:
          type: string
          format: date-time
          example: '2026-07-31T00:00:01.000Z'
