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.
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.