Webhooks

1. Create a handler

Set up your endpoint function so that it:

• Handles POST requests with JSON payloads
• Quickly returns a successfull status code 2xx prior to any complex operations that might cause a timeout

2. Test your handler

Before you go-live with your webhook endpoint function, we recommend that you test your application integration.

You can simply POST to your webhook endpoint with the following payload for a completed scan:

{
  "type": "ProcessStatus",
  "time": "2025-09-20T14:36:52.211Z",
  "data": {
    "id": "8794a2ba-b4ca-40ca-9585-ca3fc501e31d",
    "status": "Completed",
    "endedAt": "2025-09-20T14:36:52.186Z",
    "updatedAt": "2025-09-20T14:36:52.186Z"
  }
}

• type: always "ProcessStatus"
• status: one of "Running" | "Completed" | "ContinuedAsNew" | "Failed" | "Terminated" | "Suspended"
• endedAt present when status is "Completed" | "Failed" | "Terminated"

3. Register your webhook

Create your webhook in TubeLab's Developer Dashboard.

Scroll down to the "Webhooks" section and click "Create Webhook" then fill in the following:

• Payload URL: the URL of your webhook endpoint
• Secret: define a secret key to secure your webhook (optional)

Payload URLs must be Secure HTTPS URLs and be in the following format:

https://<your-website>/<your-webhook-endpoint>

4. Secure your webhook (optional)

You can set a secret to verify that a webhook delivery is from TubeLab.

To do this, you need to:

1. Create a secret token for your webhook
2. Store the secret on your server
3. Validate incoming requests using the payload & secret

Start by going to TubeLab's Developer Dashboard. On the webhook row, click on the actions and "Edit". Here you can set the secret token or change an existing one.

When a secret is set, all requests will include a X-TubeLab-Signature-256 header with a HMAC-SHA256 signature of the request body.

Headers example:

// headers
"x-tubelab-signature-256": "sha256=9db81febbc4334e338ce23e783e9114a012d68aae59e51eba375ed9493d67f80",
"x-tubelab-delivery": "6f8a7b0b-5602-49b8-9dbf-a1c7bc02bb5f",
"x-tubelab-event": "ProcessStatus",
"x-tubelab-hook-id": "d0b88613-9ca6-4de2-b692-31b869173e76",