brevo-webhooks-openapi.yml

openapi: 3.1.0
info:
  title: Brevo Webhooks API
  description: >-
    The Brevo Webhooks API allows developers to receive real-time
    notifications when events occur across transactional emails, marketing
    campaigns, and conversations. By configuring webhook subscriptions,
    applications can automatically receive data for events such as email
    deliveries, opens, clicks, bounces, spam reports, and unsubscribes. This
    eliminates the need for polling and enables event-driven integrations that
    respond immediately to changes in messaging activity.
  version: '3.0'
  contact:
    name: Brevo Support
    url: https://help.brevo.com
  termsOfService: https://www.brevo.com/legal/termsofuse/
externalDocs:
  description: Brevo Webhooks Documentation
  url: https://developers.brevo.com/docs/transactional-webhooks
servers:
  - url: https://api.brevo.com/v3
    description: Brevo Production API Server
tags:
  - name: Webhooks
    description: >-
      Create, manage, and configure webhook subscriptions for receiving
      real-time event notifications.
security:
  - apiKeyAuth: []
paths:
  /webhooks:
    get:
      operationId: listWebhooks
      summary: Get all webhooks
      description: >-
        Retrieves all webhook subscriptions configured in the account.
        Supports filtering by webhook type to view transactional,
        marketing, or inbound webhook configurations.
      tags:
        - Webhooks
      parameters:
        - name: type
          in: query
          description: >-
            Filter webhooks by type. Returns all types if not specified.
          schema:
            type: string
            enum:
              - transactional
              - marketing
              - inbound
        - name: sort
          in: query
          description: >-
            Sort direction for the results.
          schema:
            type: string
            enum:
              - asc
              - desc
      responses:
        '200':
          description: Webhooks retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookList'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      operationId: createWebhook
      summary: Create a webhook
      description: >-
        Creates a new webhook subscription to receive real-time event
        notifications at the specified URL. The webhook can be configured
        for transactional, marketing, or inbound event types.
      tags:
        - Webhooks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWebhook'
      responses:
        '201':
          description: Webhook created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    format: int64
                    description: >-
                      Unique identifier of the newly created webhook.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /webhooks/{webhookId}:
    get:
      operationId: getWebhook
      summary: Get a webhook
      description: >-
        Retrieves the details of a specific webhook subscription
        including its URL, event types, and configuration.
      tags:
        - Webhooks
      parameters:
        - $ref: '#/components/parameters/webhookIdParam'
      responses:
        '200':
          description: Webhook retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Webhook not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      operationId: updateWebhook
      summary: Update a webhook
      description: >-
        Updates an existing webhook subscription with new URL, event
        types, or configuration options.
      tags:
        - Webhooks
      parameters:
        - $ref: '#/components/parameters/webhookIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateWebhook'
      responses:
        '204':
          description: Webhook updated successfully
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Webhook not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      operationId: deleteWebhook
      summary: Delete a webhook
      description: >-
        Permanently deletes a webhook subscription. Events will no
        longer be sent to the configured URL.
      tags:
        - Webhooks
      parameters:
        - $ref: '#/components/parameters/webhookIdParam'
      responses:
        '204':
          description: Webhook deleted successfully
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Webhook not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: api-key
      description: >-
        Brevo API key passed in the api-key request header for
        authentication.
  parameters:
    webhookIdParam:
      name: webhookId
      in: path
      required: true
      description: >-
        Unique identifier of the webhook subscription.
      schema:
        type: integer
        format: int64
  schemas:
    WebhookList:
      type: object
      properties:
        webhooks:
          type: array
          description: >-
            List of webhook subscriptions.
          items:
            $ref: '#/components/schemas/Webhook'
    Webhook:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: >-
            Unique identifier of the webhook.
        url:
          type: string
          format: uri
          description: >-
            URL where event notifications are delivered.
        description:
          type: string
          description: >-
            Human-readable description of the webhook purpose.
        type:
          type: string
          description: >-
            Type of webhook determining which event categories apply.
          enum:
            - transactional
            - marketing
            - inbound
        events:
          type: array
          description: >-
            List of event types the webhook is subscribed to.
          items:
            type: string
        isActive:
          type: boolean
          description: >-
            Whether the webhook is currently active and receiving events.
        createdAt:
          type: string
          format: date-time
          description: >-
            UTC date-time when the webhook was created.
        modifiedAt:
          type: string
          format: date-time
          description: >-
            UTC date-time when the webhook was last modified.
    CreateWebhook:
      type: object
      required:
        - url
        - events
        - type
      properties:
        url:
          type: string
          format: uri
          description: >-
            URL to receive webhook event notifications. Must be a valid
            HTTPS endpoint.
        description:
          type: string
          description: >-
            Human-readable description of the webhook purpose.
        type:
          type: string
          description: >-
            Type of webhook. Determines available event types.
          enum:
            - transactional
            - marketing
            - inbound
        events:
          type: array
          description: >-
            Event types to subscribe to. For transactional type, possible
            values include sent, delivered, hardBounce, softBounce,
            blocked, spam, invalid, deferred, click, opened, uniqueOpened,
            and unsubscribed. For marketing type, possible values include
            unsubscribed, listAddition, and delivered. For inbound type,
            the value is inboundEmailProcessed.
          items:
            type: string
            enum:
              - sent
              - request
              - delivered
              - hardBounce
              - softBounce
              - blocked
              - spam
              - invalid
              - deferred
              - click
              - opened
              - uniqueOpened
              - unsubscribed
              - listAddition
              - inboundEmailProcessed
        domain:
          type: string
          description: >-
            Optional domain filter to receive events only for emails
            sent from this domain.
    UpdateWebhook:
      type: object
      properties:
        url:
          type: string
          format: uri
          description: >-
            Updated URL to receive webhook notifications.
        description:
          type: string
          description: >-
            Updated description.
        events:
          type: array
          description: >-
            Updated list of event types to subscribe to.
          items:
            type: string
            enum:
              - sent
              - request
              - delivered
              - hardBounce
              - softBounce
              - blocked
              - spam
              - invalid
              - deferred
              - click
              - opened
              - uniqueOpened
              - unsubscribed
              - listAddition
              - inboundEmailProcessed
        domain:
          type: string
          description: >-
            Updated domain filter.
    ErrorResponse:
      type: object
      properties:
        code:
          type: string
          description: >-
            Error code identifying the type of error.
        message:
          type: string
          description: >-
            Human-readable description of the error.