Documentation

Overview

Webhooks allow you to receive automated HTTP notifications when events occur in your Improvado workspace — such as connection status changes, extraction completions, data table updates, and more. Instead of polling the API, your server gets notified automatically.

Event delivery may be delayed by up to ~15 minutes after the event occurs. Webhooks are designed for automation and integration workflows, not for use cases that require instant reaction.

You can manage webhooks from Settings → Notification Center → Webhooks.

Adding a Webhook

To start receiving event notifications, register your existing server endpoint in Improvado:

1. Navigate to Settings → Notification Center.
2. Scroll to the Webhooks section and click Add.
3. Enter the URL of your server that will receive webhook events (the endpoint must already be deployed and publicly accessible).
4. Select the event types you want to subscribe to.
5. Click Save.

After registration, the webhook will be in Unverified status. Events will not be delivered until the endpoint passes verification.

Endpoint Verification

Improvado uses a challenge-response mechanism to verify that you own and control the webhook endpoint URL. Until verification is complete, the endpoint stays in unverified status and will not receive any events.

Verification Flow

1. Click the Verify button next to your webhook URL in the Notification Center.
2. Improvado generates a random challenge token and sends a GET request to your endpoint URL with the following headers:
   • X-Improvado-Challenge — a random challenge string your server must echo back.
   • X-Improvado-Verify-Token — the signing secret of your endpoint (so your server can confirm the request is from Improvado).
3. Your server must respond with:
   • HTTP status 200
   • The exact value of the X-Improvado-Challenge header as the response body (plain text).
4. If the response body matches the challenge, the endpoint status changes to active and events will start being delivered.

Verification Errors

• Challenge response did not match — your server returned a response, but the body did not match the challenge value. Make sure you are returning the exact value from the X-Improvado-Challenge header.
• Failed to reach endpoint — Improvado could not connect to your URL. Verify the URL is publicly accessible and your server is running.

Event Payload

When an event occurs, Improvado sends a POST request to your endpoint with a JSON payload. Here is an example of an extraction_paused event:

{
 "id": "A1B2C3D4E5F6789012345678ABCDEF90",
 "type": "extraction_paused",
 "timestamp": "2026-04-06 11:39:46.752000",
 "data": {
   "product_domain_event_inserted_at": "2026-04-06 12:00:12.000",
   "product_domain_event_aggregate_class": "Extraction",
   "product_domain_event_class": "ExtractionPaused",
   "product_domain_event_usecase": "PauseExtractionUseCase",
   "product_domain_event": "",
   "is_action_log": "1",
   "agency_title": "My Agency",
   "workspace_title": "Main Workspace",
   "dts_order_params_id": "123456",
   "order_id": "654321"
 }
}
  

‍‍Each event contains:

• id — unique event identifier
• type — the event type name (matches your subscription)
• timestamp — when the event occurred
• data — event-specific payload with details about what happened

Signing Secret

Each webhook has a unique signing secret, visible in the Notification Center while the endpoint is unverified. Use this secret to verify that incoming webhook requests are genuinely from Improvado. During verification, the secret is sent in the X-Improvado-Verify-Token header. During event delivery, the secret is used to compute an HMAC-SHA256 signature sent in the X-Improvado-Signature header — compute the same signature on your side and compare.

Event delivery requests also include an X-Improvado-Idempotency-Key header that you can use to deduplicate events.

Managing Subscriptions

Each webhook can subscribe to specific event types. You can update subscriptions at any time by editing the Subscribed events field on the webhook card. Use the clear button to remove all subscriptions, or select individual events from the dropdown.

Available event categories include:

• Account events — account created, enabled, disabled, name changed
• Connection events — connection created, deleted, invalidated, reconnected
• Extraction events — extraction created, paused, unpaused, fields changed, downloads started
• Load events — load created, started, completed, paused
• Transformation events — transformation created, started, completed
• Data table events — table created, title changed, freshness changed
• User events — user invited, added to workspace, removed, role changed
• Recipe events — recipe activated, deactivated, promoted, validated

Webhook Statuses

• Unverified — the endpoint has not passed the challenge-response verification. No events will be delivered.
• Active — the endpoint is verified and receiving events.

Best Practices

• Always validate the X-Improvado-Signature header by computing HMAC-SHA256 of the request body with your signing secret and comparing the result.
• Respond to webhook deliveries with a 2xx status code promptly. Long-running processing should be done asynchronously.
• Use the X-Improvado-Idempotency-Key header to deduplicate events in case of retries.
• Keep your endpoint URL publicly accessible and ensure TLS (HTTPS) is configured.