Webhook Configuration#

Manage the campaign's webhook without leaving your systems: read the current configuration, point it at a new URL, and pause or resume delivery. The campaign is taken from your API key, so there is no id in the path. There is one webhook configuration per campaign — it is shared across live and test mode (every event carries a livemode flag so you can tell them apart). For payload formats see Webhook Events; for delivery, signing, and retries see the Webhooks guide.

Get the configuration#

GET/v1/webhook

Get the webhook configuration

Returns the campaign's current webhook endpoint URL and enabled flag.

Responses

200The current webhook configuration.

Example

{
  "endpoint_url": "string",
  "is_active": true,
  "updated_at": "2026-01-15T12:00:00Z",
  "hmac_secret": "string"
}

{  "endpoint_url": "string",  "is_active": true,  "updated_at": "2026-01-15T12:00:00Z",  "hmac_secret": "string"}

Schema

endpoint_urlstringrequired

HTTPS URL that receives webhook events.

is_activebooleanrequired

Whether webhook delivery is enabled.

updated_atstring<date-time>required

When the configuration was last updated.

hmac_secretunknown

HMAC-SHA256 signing secret — returned only when the configuration is first created.

401Invalid or missing API key.

404No webhook configuration exists for this campaign.

Returns the campaign's current webhook configuration. Responds 404 if none has been set up yet. The signing secret is never returned here.

endpoint_urlstring

The HTTPS URL events are delivered to.

is_activeboolean

Whether delivery is enabled. When false, events are skipped — nothing is delivered.

updated_atstring<date-time>

When the configuration was last changed.

Update the configuration#

PATCH/v1/webhook

Update the webhook configuration

Updates the campaign's webhook endpoint URL and/or enables/disables delivery. Creates the configuration when none exists yet — in that case the signing secret is returned once, only in the creation response.

Request Body

Example

{
  "endpoint_url": "string",
  "is_active": true
}

{  "endpoint_url": "string",  "is_active": true}

Schema

endpoint_urlunknown

HTTPS URL that receives webhook events.

is_activeunknown

Whether webhook delivery is enabled. Set to false to pause delivery.

Responses

200Webhook configuration updated.

Example

{
  "endpoint_url": "string",
  "is_active": true,
  "updated_at": "2026-01-15T12:00:00Z",
  "hmac_secret": "string"
}

{  "endpoint_url": "string",  "is_active": true,  "updated_at": "2026-01-15T12:00:00Z",  "hmac_secret": "string"}

Schema

endpoint_urlstringrequired

HTTPS URL that receives webhook events.

is_activebooleanrequired

Whether webhook delivery is enabled.

updated_atstring<date-time>required

When the configuration was last updated.

hmac_secretunknown

HMAC-SHA256 signing secret — returned only when the configuration is first created.

201Webhook configuration created — response includes hmac_secret.

401Invalid or missing API key.

422Validation error (invalid URL, or endpoint_url missing on create).

Updates the endpoint URL and/or the enabled flag — send either or both. If no configuration exists yet, this creates one and responds 201, returning the generated signing secret once (see the callout below). Updating an existing configuration responds 200 and never returns the secret.

endpoint_urlstring

The HTTPS URL events are delivered to. Must start with https://. Required when creating the configuration; optional when updating (omit to leave the URL unchanged).

is_activeboolean

Enable (true) or disable (false) delivery. Omit to leave it unchanged. Defaults to true on creation. Set false to pause webhooks without losing the endpoint or secret.

The signing secret is shown once

hmac_secret is returned only in the 201 response that first creates the configuration. Store it then — it is never returned again by this endpoint. If you lose it, rotate it from the Evolu dashboard.

Example#

curl -X PATCH https://api.evolu.tec.br/v1/webhook \
  -H "Authorization: Bearer evolu_live_aB3dE6gH_x7K2p..." \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint_url": "https://hooks.acme.com/evolu",
    "is_active": true
  }'

curl -X PATCH https://api.evolu.tec.br/v1/webhook \  -H "Authorization: Bearer evolu_live_aB3dE6gH_x7K2p..." \  -H "Content-Type: application/json" \  -d '{    "endpoint_url": "https://hooks.acme.com/evolu",    "is_active": true  }'

const response = await fetch('https://api.evolu.tec.br/v1/webhook', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${EVOLU_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    endpoint_url: 'https://hooks.acme.com/evolu',
    is_active: true,
  }),
})

const response = await fetch('https://api.evolu.tec.br/v1/webhook', {  method: 'PATCH',  headers: {    Authorization: `Bearer ${EVOLU_API_KEY}`,    'Content-Type': 'application/json',  },  body: JSON.stringify({    endpoint_url: 'https://hooks.acme.com/evolu',    is_active: true,  }),})

import requests

response = requests.patch(
    "https://api.evolu.tec.br/v1/webhook",
    headers={
        "Authorization": f"Bearer {EVOLU_API_KEY}",
        "Content-Type": "application/json",
    },
    json={"endpoint_url": "https://hooks.acme.com/evolu", "is_active": True},
)

import requestsresponse = requests.patch(    "https://api.evolu.tec.br/v1/webhook",    headers={        "Authorization": f"Bearer {EVOLU_API_KEY}",        "Content-Type": "application/json",    },    json={"endpoint_url": "https://hooks.acme.com/evolu", "is_active": True},)

A 201 (created) response includes the secret; a 200 (updated) response does not:

{
  "endpoint_url": "https://hooks.acme.com/evolu",
  "is_active": true,
  "updated_at": "2026-06-08T14:30:00Z",
  "hmac_secret": "3f9a...e1b0"
}

{  "endpoint_url": "https://hooks.acme.com/evolu",  "is_active": true,  "updated_at": "2026-06-08T14:30:00Z",  "hmac_secret": "3f9a...e1b0"}

{
  "endpoint_url": "https://hooks.acme.com/evolu",
  "is_active": true,
  "updated_at": "2026-06-08T14:31:22Z"
}

{  "endpoint_url": "https://hooks.acme.com/evolu",  "is_active": true,  "updated_at": "2026-06-08T14:31:22Z"}

Errors#

Status	Cause
`401`	Missing or invalid API key.
`404`	`GET` only — no webhook configuration exists for this campaign yet.
`422`	Invalid `endpoint_url` (must be HTTPS), or `endpoint_url` omitted while creating the configuration.