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

labId

string

required

Lab this webhook is scoped to.

url

string

required

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

events

string[]

required

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

secret

string

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

description

string

Human-readable description of this webhook’s purpose.

enabled

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"
  }'

data

object

Show Webhook object

_id

string

required

Convex document ID.

labId

string

required

Lab ID.

url

string

required

Destination URL.

events

string[]

required

Subscribed event types.

secret

string

required

HMAC signing secret (shown only on creation).

description

string

Description.

enabled

boolean

required

Whether active.

createdAt

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.

type

string

required

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

createdAt

number

required

Event timestamp in milliseconds.

labId

string

required

Lab the event belongs to.

data

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");
});

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"

Update a Webhook

url

string

Updated destination URL.

events

string[]

Updated event subscriptions.

enabled

boolean

Enable or disable the webhook.

description

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
  }'

Delete a Webhook

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

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"

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"

data

object[]

Show Delivery object

string

required

Delivery ID.

eventId

string

required

Event ID that triggered this delivery.

eventType

string

required

Event type.

statusCode

number

HTTP response status code.

success

boolean

required

Whether the delivery succeeded.

attempt

number

required

Attempt number (1-6).

responseTime

number

Response time in milliseconds.

error

string

Error message if the delivery failed.

createdAt

number

required

Delivery timestamp (ms).

Documentation Index

​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