agentboxd-com Webhooks API

openapi: 3.2.0
info:
  title: Agentboxd Com Webhooks API
  version: '1'
  contact:
    name: Agentboxd
    url: https://agentboxd.com
    email: hello@agentboxd.com
  description: 'Operations tagged Webhooks across 2 of this provider''s published API definitions: agentboxd-com-openapi.json, agentboxd-com-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.agentboxd.com
security:
- apiKey: []
tags:
- name: Webhooks
  description: Signed HTTP notifications for new mail and other events.
paths:
  /v1/webhooks:
    post:
      operationId: postWebhooks
      tags:
      - Webhooks
      summary: Create a webhook
      description: '`{ url, events?, inbox_ids?, enabled?, secret?, payload?: "full" | "envelope", headers? }`. `url` must be a public HTTPS endpoint (`422 invalid_webhook_url` otherwise). `events` lists each event type at most once; repeats are dropped. `payload: "full"` sends message and draft content, so it needs the key’s `messages:read` for message and attachment events and `drafts:read` for draft events (`403 insufficient_permissions` otherwise). Without `payload`, a key that lacks them gets `envelope`. The secret is returned only here. `headers`: up to 10 extra headers sent with every delivery, e.g. `{ "Authorization": "Bearer …" }` for your own check next to the signature. Values are stored encrypted and never returned (webhooks show `header_names`); `Host`, `Content-Type` and our `X-Mailroom-*` headers can’t be set. On `PATCH`, `headers` replaces the set and `null` clears it. A workspace can have up to 20 webhooks (`409 webhook_limit_reached`); one webhook can take any number of event types and inboxes.


        Permission: `webhooks:manage`.'
      x-permission: webhooks:manage
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                  maxLength: 2048
                  format: uri
                events:
                  minItems: 1
                  maxItems: 41
                  type: array
                  items:
                    type: string
                    enum:
                    - message.received
                    - message.sent
                    - message.delivered
                    - message.bounced
                    - message.complained
                    - message.enriched
                    - message.released
                    - inbox.expired
                    - message.received.blocked
                    - draft.created
                    - draft.updated
                    - draft.sent
                    - draft.failed
                    - draft.cancelled
                    - identity.token_issued
                    - identity.signed_in
                    - signup.created
                    - signup.claimed
                    - attachment.extracted
                    - attachment.extraction_failed
                    - inbox.paused
                    - inbox.resumed
                    - domain.dkim_rotated
                    - domain.dkim_rotation_due
                    - domain.verified
                    - domain.failed
                    - connector.authorized
                    - connector.revoked
                    - workspace.stopped
                    - workspace.resumed
                    - escalation.sent
                    - agent.updated
                    - agent.revoked
                    - agent.deleted
                    - agent.reported
                    - member.invited
                    - member.invite_revoked
                    - member.joined
                    - member.role_changed
                    - member.removed
                    - suppression.removed
                inbox_ids:
                  anyOf:
                  - minItems: 1
                    maxItems: 1000
                    type: array
                    items:
                      type: string
                      format: uuid
                      pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                  - type: 'null'
                enabled:
                  type: boolean
                secret:
                  type: string
                  minLength: 16
                  maxLength: 256
                payload:
                  type: string
                  enum:
                  - full
                  - envelope
                headers:
                  type: object
                  propertyNames:
                    type: string
                    pattern: ^[A-Za-z0-9][A-Za-z0-9-]{0,63}$
                  additionalProperties:
                    type: string
                    minLength: 1
                    maxLength: 1024
                    pattern: ^[^\r\n]*$
              required:
              - url
              additionalProperties: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        4XX:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        5XX:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    get:
      operationId: getWebhooks
      tags:
      - Webhooks
      summary: List webhooks
      description: 'Returns `secret_hint`, never the secret, and `stats`: `deliveries_24h`, `failed_24h`, `error_rate_24h`, `last_success_at`, `last_failure_at`.


        Permission: `webhooks:manage`.'
      x-permission: webhooks:manage
      parameters:
      - name: cursor
        in: query
        required: false
        schema:
          type: string
      - name: limit
        in: query
        required: false
        schema:
          default: 25
          type: integer
          minimum: 1
          maximum: 100
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        4XX:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        5XX:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    servers:
    - url: https://api.agentboxd.com
  /v1/webhooks/{id}:
    get:
      operationId: getWebhooksById
      tags:
      - Webhooks
      summary: Get a webhook
      description: 'Returns `secret_hint`, never the secret, and `stats`: `deliveries_24h`, `failed_24h`, `error_rate_24h`, `last_success_at`, `last_failure_at`.


        Permission: `webhooks:manage`.'
      x-permission: webhooks:manage
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        4XX:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        5XX:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    patch:
      operationId: patchWebhooksById
      tags:
      - Webhooks
      summary: Update a webhook
      description: 'Change events, scope, `payload` or `enabled`; delete. Moving a full-payload webhook to another `url`, switching it to `full` or adding events needs the same permissions as creating it.


        Permission: `webhooks:manage`.'
      x-permission: webhooks:manage
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                  maxLength: 2048
                  format: uri
                events:
                  minItems: 1
                  maxItems: 41
                  type: array
                  items:
                    type: string
                    enum:
                    - message.received
                    - message.sent
                    - message.delivered
                    - message.bounced
                    - message.complained
                    - message.enriched
                    - message.released
                    - inbox.expired
                    - message.received.blocked
                    - draft.created
                    - draft.updated
                    - draft.sent
                    - draft.failed
                    - draft.cancelled
                    - identity.token_issued
                    - identity.signed_in
                    - signup.created
                    - signup.claimed
                    - attachment.extracted
                    - attachment.extraction_failed
                    - inbox.paused
                    - inbox.resumed
                    - domain.dkim_rotated
                    - domain.dkim_rotation_due
                    - domain.verified
                    - domain.failed
                    - connector.authorized
                    - connector.revoked
                    - workspace.stopped
                    - workspace.resumed
                    - escalation.sent
                    - agent.updated
                    - agent.revoked
                    - agent.deleted
                    - agent.reported
                    - member.invited
                    - member.invite_revoked
                    - member.joined
                    - member.role_changed
                    - member.removed
                    - suppression.removed
                inbox_ids:
                  anyOf:
                  - minItems: 1
                    maxItems: 1000
                    type: array
                    items:
                      type: string
                      format: uuid
                      pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                  - type: 'null'
                enabled:
                  type: boolean
                payload:
                  type: string
                  enum:
                  - full
                  - envelope
                headers:
                  anyOf:
                  - type: object
                    propertyNames:
                      type: string
                      pattern: ^[A-Za-z0-9][A-Za-z0-9-]{0,63}$
                    additionalProperties:
                      type: string
                      minLength: 1
                      maxLength: 1024
                      pattern: ^[^\r\n]*$
                  - type: 'null'
              additionalProperties: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        4XX:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        5XX:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      operationId: deleteWebhooksById
      tags:
      - Webhooks
      summary: Delete a webhook
      description: 'Change events, scope, `payload` or `enabled`; delete. Moving a full-payload webhook to another `url`, switching it to `full` or adding events needs the same permissions as creating it.


        Permission: `webhooks:manage`.'
      x-permission: webhooks:manage
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        4XX:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        5XX:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    servers:
    - url: https://api.agentboxd.com
  /v1/webhooks/{id}/deliveries:
    get:
      operationId: getWebhooksByIdDeliveries
      tags:
      - Webhooks
      summary: List a webhook’s deliveries
      description: '`?status=pending|succeeded|failed&cursor=&limit=`, newest first: `{ data: [{ id, event_id, event_type, status, attempts, last_status_code, last_error, last_response_ms, next_attempt_at, last_attempt_at, redelivered_at, created_at }], next_cursor }`. Each row is one event sent to this webhook; `attempts` is the number of its latest attempt, `last_response_ms` how long that attempt took. Deliveries are kept as long as their event (message, attachment, draft and agent events follow your retention).


        Permission: `webhooks:manage`.'
      x-permission: webhooks:manage
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
      - name: cursor
        in: query
        required: false
        schema:
          type: string
      - name: limit
        in: query
        required: false
        schema:
          default: 25
          type: integer
          minimum: 1
          maximum: 100
      - name: status
        in: query
        required: false
        schema:
          type: string
          enum:
          - pending
          - succeeded
          - failed
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        4XX:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        5XX:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    servers:
    - url: https://api.agentboxd.com
  /v1/webhooks/{id}/deliveries/{deliveryId}/redeliver:
    post:
      operationId: postWebhooksByIdDeliveriesByDeliveryIdRedeliver
      tags:
      - Webhooks
      summary: Send a delivery again
      description: 'Sends that delivery again: the same payload, signed again with a fresh timestamp, one attempt (no retries) → `202` with the delivery, `status: "pending"`. `409 delivery_pending` while it is still being retried, `409 webhook_disabled` while the webhook is paused, `404` when it isn’t this webhook’s.


        Permission: `webhooks:manage`.'
      x-permission: webhooks:manage
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
      - name: deliveryId
        in: path
        required: true
        schema:
          type: string
          format: uuid
          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        4XX:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        5XX:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    servers:
    - url: https://api.agentboxd.com
  /v1/webhooks/{id}/redeliver:
    post:
      operationId: postWebhooksByIdRedeliver
      tags:
      - Webhooks
      summary: Send an event again, by event id
      description: '`{ event_id }`: the same, found by event id.


        Permission: `webhooks:manage`.'
      x-permission: webhooks:manage
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                event_id:
                  type: string
                  format: uuid
                  pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
              required:
              - event_id
              additionalProperties: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        4XX:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        5XX:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    servers:
    - url: https://api.agentboxd.com
  /v1/webhooks/{id}/rotate-secret:
    post:
      operationId: postWebhooksByIdRotateSecret
      tags:
      - Webhooks
      summary: Rotate a webhook’s signing secret
      description: '`{ secret? }`: replaces the signing secret with yours (16–256 characters) or a generated one, and returns it once. See Rotate the secret.


        Permission: `webhooks:manage`.'
      x-permission: webhooks:manage
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                secret:
                  type: string
                  minLength: 16
                  maxLength: 256
              additionalProperties: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        4XX:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        5XX:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    servers:
    - url: https://api.agentboxd.com
  /v1/webhooks/{id}/test:
    post:
      operationId: postWebhooksByIdTest
      tags:
      - Webhooks
      summary: Send a test event
      description: 'Sends a `webhook.test` event.


        Permission: `webhooks:manage`.'
      x-permission: webhooks:manage
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        4XX:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        5XX:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    servers:
    - url: https://api.agentboxd.com
  /v1/webhooks/events:
    get:
      operationId: getWebhooksEvents
      tags:
      - Webhooks
      summary: List event types
      description: 'Public. Every event type with a description and an example payload. Webhooks accept `payload: "envelope"` for ids, addresses, subject and labels only: no bodies or AI content.'
      security: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        4XX:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        5XX:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    servers:
    - url: https://api.agentboxd.com
components:
  schemas:
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              description: Stable, machine-readable error code.
            message:
              type: string
              description: What happened and how to fix it, in plain words.
            details:
              description: 'The specifics: which recipient, which limit, until when.'
            docs_url:
              type: string
              format: uri
              description: 'For a refused send: its entry on "Why was my send refused?" (https://agentboxd.com/docs/send-refusals).'
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: An API key (`mr_…`), scoped to the workspace or one inbox, with a set of permissions.
externalDocs:
  description: API reference
  url: https://agentboxd.com/docs/api
x-refined-from:
- agentboxd-com-openapi.json
- agentboxd-com-openapi.json