Webhooks

Manage webhook endpoints that receive event notifications from Improvado.

Webhooks let your application react to platform events (extraction completion, load completion, etc.) in near real time, without polling. Each endpoint is workspace-scoped and subscribes to one or more event types.

Lifecycle:

Register an endpoint with the URL of your receiver and the event types you care about. Improvado returns an id and a secret, and the endpoint is created in unverified status.
Verify ownership by calling the verify action. Improvado sends a GET request to your URL with X-Improvado-Verify-Token and X-Improvado-Challenge headers. Your receiver must respond with HTTP 200 and the challenge value as the response body. After successful verification the endpoint moves to active.
Receive events. Improvado POSTs JSON payloads {id, type, timestamp, data} to your URL. Each request is signed with HMAC-SHA256 in the X-Improvado-Signature header (using the endpoint's secret) and includes X-Improvado-Idempotency-Key for safe retry handling.
Rotate the secret at any time. Rotation invalidates the previous secret immediately and resets the endpoint to unverified until you re-verify.

Failed deliveries are retried up to four times with backoff [0s, 2s, 5s, 10s]. Receivers should aim to respond within a few seconds and return 2xx for successful processing.

List webhook endpoints

GET

https://embedded.improvado.io

/api/v3/webhook_endpoints/

List webhook endpoints registered in the current workspace.

List webhook endpoints › Responses

A paginated list of webhook endpoints

PaginatedWebhookEndpointList

count

integer

next

string | null

previous

string | null

WebhookEndpointListItem[]

Create a webhook endpoint

POST

https://embedded.improvado.io

/api/v3/webhook_endpoints/

Register a new webhook endpoint and subscribe it to one or more event types. The endpoint is created in unverified status and a fresh secret is returned in the response. Use the verify action to activate the endpoint.

Important: event_types must contain identifiers returned by GET /api/v3/webhook_event_types/ (e.g. load_completed, transformation_completed). Unknown event names are accepted by the request but no deliveries will be sent for them — always source the names from the event types endpoint rather than hard-coding them.

Create a webhook endpoint › Request Body

WebhookEndpointCreateRequest

url

string · uri · maxLength: 2048 · required

HTTPS URL of the receiver that will accept event deliveries.

event_types

string[]

Event types this endpoint will subscribe to. See GET /api/v3/webhook_event_types/ for the list of available event names. Duplicates are deduplicated server-side. May be empty.

Create a webhook endpoint › Responses

Webhook endpoint created

Full webhook endpoint representation, including the signing secret and the list of subscriptions. The `secret` is used to compute the `X-Improvado-Signature` header (HMAC-SHA256) on every event delivery and as the verification token during the verify flow. Treat it as sensitive and store it securely.

WebhookEndpointDetail

id

integer

url

string · uri

secret

string

64-character hex signing secret

status

string · enum

Enum values:

unverified

active

consecutive_failures

integer

WebhookSubscription[]

created_at

string · date-time

updated_at

string · date-time

POST/api/v3/webhook_endpoints/

curl --request POST \
  --url https://embedded.improvado.io/api/v3/webhook_endpoints/ \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "https://customer.example.com/improvado/webhooks",
  "event_types": [
    "load_completed",
    "transformation_completed"
  ]
}
'

shell

Example Request Body

{
  "url": "https://customer.example.com/improvado/webhooks",
  "event_types": [
    "load_completed",
    "transformation_completed"
  ]
}

json

application/json

Example Responses

{
  "id": 42,
  "url": "https://customer.example.com/improvado/webhooks",
  "secret": "1f9e4b3a8c2d6e0f7a5b9c1d3e2f4a6b8c0d2e4f6a8b0c2d4e6f8a0b2c4d6e8f",
  "status": "unverified",
  "consecutive_failures": 0,
  "subscriptions": [
    {
      "id": 100,
      "event_type_name": "load_completed",
      "is_active": true,
      "created_at": "2026-04-25T10:15:00Z"
    },
    {
      "id": 101,
      "event_type_name": "transformation_completed",
      "is_active": true,
      "created_at": "2026-04-25T10:15:00Z"
    }
  ],
  "created_at": "2026-04-25T10:15:00Z",
  "updated_at": "2026-04-25T10:15:00Z"
}

json

application/json

Get a webhook endpoint

GET

https://embedded.improvado.io

/api/v3/webhook_endpoints/{id}/

Retrieve detailed information about a webhook endpoint, including its current subscriptions and signing secret.

Get a webhook endpoint › path Parameters

id

integer · required

Webhook endpoint ID

Get a webhook endpoint › Responses

Webhook endpoint detail

WebhookEndpointDetail

id

integer

url

string · uri

secret

string

64-character hex signing secret

status

string · enum

Enum values:

unverified

active

consecutive_failures

integer

WebhookSubscription[]

created_at

string · date-time

updated_at

string · date-time

Delete a webhook endpoint

DELETE

https://embedded.improvado.io

/api/v3/webhook_endpoints/{id}/

Permanently delete a webhook endpoint and all of its subscriptions. Pending and in-flight deliveries for this endpoint are abandoned.

Delete a webhook endpoint › path Parameters

id

integer · required

Webhook endpoint ID

Delete a webhook endpoint › Responses

Deleted

No data returned

Update a webhook endpoint

PATCH

https://embedded.improvado.io

/api/v3/webhook_endpoints/{id}/

Partially update a webhook endpoint. Either field may be omitted.

Setting event_types replaces the full list of subscriptions for this endpoint.
Updating either field resets the endpoint status to unverified; you must call verify again before the endpoint will receive events.

Update a webhook endpoint › path Parameters

id

integer · required

Webhook endpoint ID

Update a webhook endpoint › Request Body

Partial update payload. Either field may be omitted. Setting `event_types` replaces the full set of subscriptions for the endpoint. Updating either field resets the endpoint to `unverified`.

WebhookEndpointUpdateRequest

url

string · uri · maxLength: 2048

event_types

string[]

Update a webhook endpoint › Responses

Webhook endpoint updated

WebhookEndpointDetail

id

integer

url

string · uri

secret

string

64-character hex signing secret

status

string · enum

Enum values:

unverified

active

consecutive_failures

integer

WebhookSubscription[]

created_at

string · date-time

updated_at

string · date-time

PATCH/api/v3/webhook_endpoints/{id}/

curl --request PATCH \
  --url https://embedded.improvado.io/api/v3/webhook_endpoints/:id/ \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "https://customer.example.com/improvado/webhooks/v2"
}
'

shell

Example Request Body

{
  "url": "https://customer.example.com/improvado/webhooks/v2"
}

json

application/json

Example Responses

{
  "id": 0,
  "url": "https://www.example.com/path/to/resource",
  "secret": "secret",
  "status": "unverified",
  "consecutive_failures": 0,
  "subscriptions": [
    {
      "id": 0,
      "event_type_name": "event_type_name",
      "is_active": true,
      "created_at": "2024-08-25T15:00:00Z"
    }
  ],
  "created_at": "2024-08-25T15:00:00Z",
  "updated_at": "2024-08-25T15:00:00Z"
}

json

application/json

Verify a webhook endpoint

POST

https://embedded.improvado.io

/api/v3/webhook_endpoints/{id}/verify/

Trigger ownership verification of the endpoint URL.

Improvado sends a GET request to the endpoint URL with the headers:

X-Improvado-Verify-Token — the endpoint's signing secret
X-Improvado-Challenge — a one-time random token

The receiver must respond with HTTP 200 and the value of X-Improvado-Challenge as the response body. On success, the endpoint transitions to active. On failure (non-200 status, mismatching body, or connection error), the endpoint remains unverified and a 400 is returned.

Verify a webhook endpoint › path Parameters

id

integer · required

Webhook endpoint ID

Verify a webhook endpoint › Responses

Endpoint verified successfully (status is now active)

WebhookEndpointDetail

id

integer

url

string · uri

secret

string

64-character hex signing secret

status

string · enum

Enum values:

unverified

active

consecutive_failures

integer

WebhookSubscription[]

created_at

string · date-time

updated_at

string · date-time

Rotate the signing secret

POST

https://embedded.improvado.io

/api/v3/webhook_endpoints/{id}/regenerate_secret/

Generate a new signing secret for the endpoint. The previous secret is invalidated immediately and the endpoint is reset to unverified status, so the endpoint must be re-verified before it will receive further events. Update your receiver to use the new secret before re-verification.

Rotate the signing secret › path Parameters

id

integer · required

Webhook endpoint ID

Rotate the signing secret › Responses

Secret rotated; the new secret is in the response body.

WebhookEndpointDetail

id

integer

url

string · uri

secret

string

64-character hex signing secret

status

string · enum

Enum values:

unverified

active

consecutive_failures

integer

WebhookSubscription[]

created_at

string · date-time

updated_at

string · date-time

List available webhook event types

GET

https://embedded.improvado.io

/api/v3/webhook_event_types/

List event types that can be subscribed to via event_types when creating or updating a webhook endpoint.

List available webhook event types › Responses

List of supported event types

WebhookEventType[]

An event type that can be subscribed to.

WebhookEventType

event_name

string

Identifier of the event type (used in event_types when creating subscriptions)

Recipes

Improvado Embedded API v3

Webhooks

Manage webhook endpoints that receive event notifications from Improvado.

Lifecycle:

Register an endpoint with the URL of your receiver and the event types you care about. Improvado returns an id and a secret, and the endpoint is created in unverified status.
Verify ownership by calling the verify action. Improvado sends a GET request to your URL with X-Improvado-Verify-Token and X-Improvado-Challenge headers. Your receiver must respond with HTTP 200 and the challenge value as the response body. After successful verification the endpoint moves to active.
Receive events. Improvado POSTs JSON payloads {id, type, timestamp, data} to your URL. Each request is signed with HMAC-SHA256 in the X-Improvado-Signature header (using the endpoint's secret) and includes X-Improvado-Idempotency-Key for safe retry handling.
Rotate the secret at any time. Rotation invalidates the previous secret immediately and resets the endpoint to unverified until you re-verify.

Failed deliveries are retried up to four times with backoff [0s, 2s, 5s, 10s]. Receivers should aim to respond within a few seconds and return 2xx for successful processing.

List webhook endpoints

GET

https://embedded.improvado.io

/api/v3/webhook_endpoints/

List webhook endpoints registered in the current workspace.

List webhook endpoints › Responses

A paginated list of webhook endpoints

PaginatedWebhookEndpointList

count

integer

next

string | null

previous

string | null

WebhookEndpointListItem[]

Create a webhook endpoint

POST

https://embedded.improvado.io

/api/v3/webhook_endpoints/

Important: event_types must contain identifiers returned by GET /api/v3/webhook_event_types/ (e.g. load_completed, transformation_completed). Unknown event names are accepted by the request but no deliveries will be sent for them — always source the names from the event types endpoint rather than hard-coding them.

Create a webhook endpoint › Request Body

WebhookEndpointCreateRequest

url

string · uri · maxLength: 2048 · required

HTTPS URL of the receiver that will accept event deliveries.

event_types

string[]

Event types this endpoint will subscribe to. See GET /api/v3/webhook_event_types/ for the list of available event names. Duplicates are deduplicated server-side. May be empty.

Create a webhook endpoint › Responses

Webhook endpoint created

WebhookEndpointDetail

id

integer

url

string · uri

secret

string

64-character hex signing secret

status

string · enum

Enum values:

unverified

active

consecutive_failures

integer

WebhookSubscription[]

created_at

string · date-time

updated_at

string · date-time

POST/api/v3/webhook_endpoints/

curl --request POST \
  --url https://embedded.improvado.io/api/v3/webhook_endpoints/ \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "https://customer.example.com/improvado/webhooks",
  "event_types": [
    "load_completed",
    "transformation_completed"
  ]
}
'

shell

Example Request Body

{
  "url": "https://customer.example.com/improvado/webhooks",
  "event_types": [
    "load_completed",
    "transformation_completed"
  ]
}

json

application/json

Example Responses

{
  "id": 42,
  "url": "https://customer.example.com/improvado/webhooks",
  "secret": "1f9e4b3a8c2d6e0f7a5b9c1d3e2f4a6b8c0d2e4f6a8b0c2d4e6f8a0b2c4d6e8f",
  "status": "unverified",
  "consecutive_failures": 0,
  "subscriptions": [
    {
      "id": 100,
      "event_type_name": "load_completed",
      "is_active": true,
      "created_at": "2026-04-25T10:15:00Z"
    },
    {
      "id": 101,
      "event_type_name": "transformation_completed",
      "is_active": true,
      "created_at": "2026-04-25T10:15:00Z"
    }
  ],
  "created_at": "2026-04-25T10:15:00Z",
  "updated_at": "2026-04-25T10:15:00Z"
}

json

application/json

Get a webhook endpoint

GET

https://embedded.improvado.io

/api/v3/webhook_endpoints/{id}/

Retrieve detailed information about a webhook endpoint, including its current subscriptions and signing secret.

Get a webhook endpoint › path Parameters

id

integer · required

Webhook endpoint ID

Get a webhook endpoint › Responses

Webhook endpoint detail

WebhookEndpointDetail

id

integer

url

string · uri

secret

string

64-character hex signing secret

status

string · enum

Enum values:

unverified

active

consecutive_failures

integer

WebhookSubscription[]

created_at

string · date-time

updated_at

string · date-time

Delete a webhook endpoint

DELETE

https://embedded.improvado.io

/api/v3/webhook_endpoints/{id}/

Permanently delete a webhook endpoint and all of its subscriptions. Pending and in-flight deliveries for this endpoint are abandoned.

Delete a webhook endpoint › path Parameters

id

integer · required

Webhook endpoint ID

Delete a webhook endpoint › Responses

Deleted

No data returned

Update a webhook endpoint

PATCH

https://embedded.improvado.io

/api/v3/webhook_endpoints/{id}/

Partially update a webhook endpoint. Either field may be omitted.

Setting event_types replaces the full list of subscriptions for this endpoint.
Updating either field resets the endpoint status to unverified; you must call verify again before the endpoint will receive events.

Update a webhook endpoint › path Parameters

id

integer · required

Webhook endpoint ID

Update a webhook endpoint › Request Body

Partial update payload. Either field may be omitted. Setting `event_types` replaces the full set of subscriptions for the endpoint. Updating either field resets the endpoint to `unverified`.

WebhookEndpointUpdateRequest

url

string · uri · maxLength: 2048

event_types

string[]

Update a webhook endpoint › Responses

Webhook endpoint updated

WebhookEndpointDetail

id

integer

url

string · uri

secret

string

64-character hex signing secret

status

string · enum

Enum values:

unverified

active

consecutive_failures

integer

WebhookSubscription[]

created_at

string · date-time

updated_at

string · date-time

PATCH/api/v3/webhook_endpoints/{id}/

curl --request PATCH \
  --url https://embedded.improvado.io/api/v3/webhook_endpoints/:id/ \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "https://customer.example.com/improvado/webhooks/v2"
}
'

shell

Example Request Body

{
  "url": "https://customer.example.com/improvado/webhooks/v2"
}

json

application/json

Example Responses

{
  "id": 0,
  "url": "https://www.example.com/path/to/resource",
  "secret": "secret",
  "status": "unverified",
  "consecutive_failures": 0,
  "subscriptions": [
    {
      "id": 0,
      "event_type_name": "event_type_name",
      "is_active": true,
      "created_at": "2024-08-25T15:00:00Z"
    }
  ],
  "created_at": "2024-08-25T15:00:00Z",
  "updated_at": "2024-08-25T15:00:00Z"
}

json

application/json

Verify a webhook endpoint

POST

https://embedded.improvado.io

/api/v3/webhook_endpoints/{id}/verify/

Trigger ownership verification of the endpoint URL.

Improvado sends a GET request to the endpoint URL with the headers:

X-Improvado-Verify-Token — the endpoint's signing secret
X-Improvado-Challenge — a one-time random token

Verify a webhook endpoint › path Parameters

id

integer · required

Webhook endpoint ID

Verify a webhook endpoint › Responses

Endpoint verified successfully (status is now active)

WebhookEndpointDetail

id

integer

url

string · uri

secret

string

64-character hex signing secret

status

string · enum

Enum values:

unverified

active

consecutive_failures

integer

WebhookSubscription[]

created_at

string · date-time

updated_at

string · date-time

Rotate the signing secret

POST

https://embedded.improvado.io

/api/v3/webhook_endpoints/{id}/regenerate_secret/

Rotate the signing secret › path Parameters

id

integer · required

Webhook endpoint ID

Rotate the signing secret › Responses

Secret rotated; the new secret is in the response body.

WebhookEndpointDetail

id

integer

url

string · uri

secret

string

64-character hex signing secret

status

string · enum

Enum values:

unverified

active

consecutive_failures

integer

WebhookSubscription[]

created_at

string · date-time

updated_at

string · date-time

List available webhook event types

GET

https://embedded.improvado.io

/api/v3/webhook_event_types/

List event types that can be subscribed to via event_types when creating or updating a webhook endpoint.

List available webhook event types › Responses

List of supported event types

WebhookEventType[]

An event type that can be subscribed to.

WebhookEventType

event_name

string

Identifier of the event type (used in event_types when creating subscriptions)

Recipes