Skip to main content
Webhooks let Vook push event notifications directly to your server the moment something happens — no polling required. When a resource is created, updated, or deleted in Vook, your registered endpoint receives an HTTP POST request with a structured event payload, allowing your application to react in real time.

​
How Webhooks Work

When an event occurs in Vook, the platform:
  1. Constructs a JSON event payload describing what happened
  2. Signs the payload with your webhook secret using HMAC-SHA256
  3. Sends an HTTP POST request to your registered endpoint
  4. Expects your server to respond with HTTP 200 within 5 seconds
  5. Retries failed deliveries up to 5 times with exponential backoff if your endpoint returns a non-2xx status or times out
Your endpoint only needs to acknowledge receipt quickly — do any heavy processing asynchronously after returning 200.
To receive webhooks locally during development, use a tunneling tool like ngrok or Cloudflare Tunnel to expose your local server to the internet.

​
Registering a Webhook Endpoint

1

Open Webhook Settings

Log in to app.vook.ai and navigate to Settings → Webhooks.
2

Add a new endpoint

Click Add Endpoint and enter the full HTTPS URL of your server (for example, https://yourapp.com/webhooks/vook).
3

Select events to subscribe to

Choose the event types your integration needs. You can subscribe to individual events or select All Events to receive everything.
4

Save and copy your webhook secret

Click Save. Vook generates a unique webhook secret for this endpoint — copy it immediately and store it securely as an environment variable (VOOK_WEBHOOK_SECRET). You won’t be able to view it again.
Your endpoint must be served over HTTPS. Vook does not deliver webhooks to plain HTTP URLs in production.

​
Event Payload Format

Every webhook Vook sends has the same envelope structure: 
{
  "id": "evt_abc123",
  "type": "resource.created",
  "created_at": "2024-01-15T10:30:00Z",
  "data": {
    "id": "res_xyz789",
    "name": "My Resource",
    "status": "active",
    "created_at": "2024-01-15T10:30:00Z"
  }
}
FieldTypeDescription
idstringUnique identifier for this event delivery
typestringThe event type (see Event Types below)
created_atstringISO 8601 timestamp of when the event occurred
dataobjectThe full resource object at the time of the event
Event IDs are unique per delivery attempt. If Vook retries a failed delivery, the retry carries the same id as the original attempt. Use this to deduplicate events in your handler.

​
Verifying Webhook Signatures

Always verify the webhook signature before processing any payload. Skipping this check means your endpoint will process any POST request it receives, not just ones from Vook — a serious security risk.
Every webhook request includes an X-Vook-Signature header containing an HMAC-SHA256 signature computed over the raw request body using your webhook secret. Verify it server-side before trusting the payload: 
import hashlib
import hmac
import os
from flask import Flask, request, abort

app = Flask(__name__)
webhook_secret = os.environ["VOOK_WEBHOOK_SECRET"].encode()

@app.route("/webhooks/vook", methods=["POST"])
def handle_webhook():
    # Read the raw body — use the raw bytes, not a parsed object
    raw_body = request.get_data()
    received_signature = request.headers.get("X-Vook-Signature", "")

    # Compute the expected signature
    expected_signature = hmac.new(
        webhook_secret,
        raw_body,
        hashlib.sha256,
    ).hexdigest()

    # Compare using a constant-time function to prevent timing attacks
    if not hmac.compare_digest(expected_signature, received_signature):
        abort(401, "Invalid signature")

    # Safe to process the event now
    event = request.get_json()
    print(f"Received event: {event['type']} ({event['id']})")

    if event["type"] == "resource.created":
        handle_resource_created(event["data"])
    elif event["type"] == "resource.updated":
        handle_resource_updated(event["data"])
    elif event["type"] == "resource.deleted":
        handle_resource_deleted(event["data"])

    return "", 200

def handle_resource_created(data):
    print(f"New resource created: {data['id']}")

def handle_resource_updated(data):
    print(f"Resource updated: {data['id']}")

def handle_resource_deleted(data):
    print(f"Resource deleted: {data['id']}")

​
Event Types

Vook emits the following event types. Subscribe only to the events your integration needs.
Event TypeTrigger
resource.createdA new resource is created
resource.updatedAn existing resource is modified
resource.deletedA resource is permanently deleted
resource.status_changedA resource transitions to a new status
batch.completedA batch operation finishes processing
batch.failedA batch operation fails
export.readyAn export file is ready to download
New event types may be added over time. Structure your handler with a default / else branch to gracefully ignore unknown event types without crashing — this makes your integration forward-compatible.