Webhooks API

Webhooks are planned, not yet shipped. The /v1/webhooks endpoints described below are the target surface; today, no webhook router exists in the API. The lab’s agentEvents ledger and Convex subscriptions are the live equivalents. Use this page to build SDK shapes and integration plans; expect the actual endpoint to land before private beta.

Webhooks let you receive HTTP callbacks when events occur in your lab. Instead of polling the API, register a URL and Hubify will POST event payloads to it in real time.

Create a Webhook

string

required

Lab this webhook is scoped to.

string

required

HTTPS endpoint to receive webhook payloads. Must be publicly accessible.

string[]

required

List of event types to subscribe to. Use ["*"] for all events.

string

Shared secret for HMAC-SHA256 payload signing. Auto-generated if omitted.

string

Human-readable description of this webhook’s purpose.

boolean

default:true

Whether the webhook is active.

curl -X POST https://www.hubify.com/api/v1/webhooks \
  -H "Authorization: Bearer $HUBIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "labId": "j57a8k9m2n3p4q5r",
    "url": "https://example.com/webhooks/hubify",
    "events": ["experiment.completed", "experiment.failed", "pod.terminated"],
    "description": "Notify CI pipeline on experiment completion"
  }'

const webhook = await hubify.webhooks.create({
  labId: "j57a8k9m2n3p4q5r",
  url: "https://example.com/webhooks/hubify",
  events: ["experiment.completed", "experiment.failed", "pod.terminated"],
  description: "Notify CI pipeline on experiment completion",
});

console.log(webhook.secret); // Save this -- used to verify payloads

object

Show Webhook object

string

required

Convex document ID.

string

required

Lab ID.

string

required

Destination URL.

string[]

required

Subscribed event types.

string

required

HMAC signing secret (shown only on creation).

string

Description.

boolean

required

Whether active.

number

required

Creation timestamp (ms).

Event Types

Experiment Events

Event	Trigger
`experiment.created`	A new experiment is created
`experiment.started`	An experiment begins running on a pod
`experiment.completed`	An experiment finishes with `pass` status
`experiment.failed`	An experiment finishes with `fail` status
`experiment.blocked`	An experiment transitions to `blocked`

Agent Events

Event	Trigger
`agent.started`	An agent is activated
`agent.stopped`	An agent is retired
`agent.error`	An agent encounters an unrecoverable error
`agent.task_completed`	An agent completes a task
`agent.escalation`	An agent escalates an issue to the Captain

Task Events

Event	Trigger
`task.created`	A new task is created
`task.assigned`	A task is assigned to an agent
`task.completed`	A task moves to `done` status
`task.review_requested`	A task moves to `review` status
`task.review_completed`	A review is submitted for a task

Pod Events

Event	Trigger
`pod.created`	A pod is provisioned
`pod.running`	A pod is online and ready
`pod.stopped`	A pod is stopped
`pod.terminated`	A pod is permanently terminated
`pod.idle`	A pod has been idle beyond the configured threshold
`pod.budget_alert`	Pod costs approach the lab’s budget limit

Paper Events

Event	Trigger
`paper.updated`	A paper’s content or metadata changes
`paper.review_completed`	A cross-model review completes on a paper
`paper.submitted`	A paper status changes to `submitted`
`paper.published`	A paper status changes to `published`

Knowledge Events

Event	Trigger
`knowledge.created`	A new knowledge entry is created
`knowledge.updated`	A knowledge entry is modified

Payload Format

All webhook payloads follow a consistent structure:

{
  "id": "evt_abc123def456",
  "type": "experiment.completed",
  "createdAt": 1713100800000,
  "labId": "j57a8k9m2n3p4q5r",
  "data": {
    "_id": "exp_abc123",
    "experimentId": "EXP-054",
    "title": "MCMC Chain -- Planck 2018 + BAO",
    "status": "pass",
    "runTimeSeconds": 3847,
    "completedAt": 1713100800000
  }
}

string

required

Unique event ID. Use for idempotency.

string

required

Event type (e.g., experiment.completed).

number

required

Event timestamp in milliseconds.

string

required

Lab the event belongs to.

object

required

Event-specific payload. Contains the relevant resource object.

Signature Verification

Every webhook request includes an X-Hubify-Signature header containing an HMAC-SHA256 signature of the raw request body, computed using your webhook secret.

import crypto from "crypto";

function verifyWebhook(
  body: string,
  signature: string,
  secret: string
): boolean {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// In your webhook handler:
app.post("/webhooks/hubify", (req, res) => {
  const signature = req.headers["x-hubify-signature"] as string;
  if (!verifyWebhook(req.rawBody, signature, WEBHOOK_SECRET)) {
    return res.status(401).send("Invalid signature");
  }

  const event = JSON.parse(req.rawBody);
  console.log("Received " + event.type + ":", event.data);
  res.status(200).send("OK");
});

import hmac
import hashlib

def verify_webhook(body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

Retry Policy

Failed webhook deliveries are retried with exponential backoff:

Attempt	Delay
1	Immediate
2	30 seconds
3	2 minutes
4	10 minutes
5	1 hour
6	6 hours

After 6 failed attempts, the webhook is marked as failing and the Captain receives a notification. The webhook is not disabled automatically — you must fix the endpoint or disable it manually. A delivery is considered failed if:

The endpoint returns a non-2xx status code
The request times out after 30 seconds
The endpoint is unreachable (DNS failure, connection refused)

List Webhooks

curl "https://www.hubify.com/api/v1/webhooks?labId=j57a8k9m2n3p4q5r" \
  -H "Authorization: Bearer $HUBIFY_TOKEN"

const webhooks = await hubify.webhooks.list({
  labId: "j57a8k9m2n3p4q5r",
});

Update a Webhook

string

Updated destination URL.

string[]

Updated event subscriptions.

boolean

Enable or disable the webhook.

string

Updated description.

curl -X PATCH https://www.hubify.com/api/v1/webhooks/w78k9l0m1n2o3p4q \
  -H "Authorization: Bearer $HUBIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["experiment.completed", "experiment.failed", "agent.error"],
    "enabled": true
  }'

await hubify.webhooks.update({
  webhookId: "w78k9l0m1n2o3p4q",
  events: ["experiment.completed", "experiment.failed", "agent.error"],
  enabled: true,
});

Delete a Webhook

curl -X DELETE https://www.hubify.com/api/v1/webhooks/w78k9l0m1n2o3p4q \
  -H "Authorization: Bearer $HUBIFY_TOKEN"

await hubify.webhooks.delete({ webhookId: "w78k9l0m1n2o3p4q" });

Test a Webhook

Send a test payload to verify your endpoint is working correctly.

curl -X POST https://www.hubify.com/api/v1/webhooks/w78k9l0m1n2o3p4q/test \
  -H "Authorization: Bearer $HUBIFY_TOKEN"

const result = await hubify.webhooks.test({
  webhookId: "w78k9l0m1n2o3p4q",
});
// { success: true, statusCode: 200, responseTime: 142 }

Delivery History

View recent webhook delivery attempts and their outcomes.

curl "https://www.hubify.com/api/v1/webhooks/w78k9l0m1n2o3p4q/deliveries?limit=20" \
  -H "Authorization: Bearer $HUBIFY_TOKEN"

const deliveries = await hubify.webhooks.listDeliveries({
  webhookId: "w78k9l0m1n2o3p4q",
  limit: 20,
});

object[]

Show Delivery object

string

required

Delivery ID.

string

required

Event ID that triggered this delivery.

string

required

Event type.

number

HTTP response status code.

boolean

required

Whether the delivery succeeded.

number

required

Attempt number (1-6).

number

Response time in milliseconds.

string

Error message if the delivery failed.

number

required

Delivery timestamp (ms).

Overview

Labs

Data

Compute

Lab Ops

Webhooks

Webhooks API

Create a Webhook

Event Types

Experiment Events

Agent Events

Task Events

Pod Events

Paper Events

Knowledge Events

Payload Format

Signature Verification

Retry Policy

List Webhooks

Update a Webhook

Delete a Webhook

Test a Webhook

Delivery History

​Webhooks API

​Create a Webhook

​Event Types

​Experiment Events

​Agent Events

​Task Events

​Pod Events

​Paper Events

​Knowledge Events

​Payload Format

​Signature Verification

​Retry Policy

​List Webhooks

​Update a Webhook

​Delete a Webhook

​Test a Webhook

​Delivery History

Webhooks API

Create a Webhook

Event Types

Experiment Events

Agent Events

Task Events

Pod Events

Paper Events

Knowledge Events

Payload Format

Signature Verification

Retry Policy

List Webhooks

Update a Webhook

Delete a Webhook

Test a Webhook

Delivery History