Ittybit

Overview

Webhooks let your app automatically receive notifications when something happens in your Ittybit project — such as when a task succeeds, a run completes, or a task fails.

Instead of polling the API for status changes, you can register webhook endpoints that receive real-time POST requests with event data.

Webhook Endpoints

Webhook endpoints are a dedicated resource in the API. You create, list, update, and delete them via the /webhooks/endpoints API.

Creating a webhook endpoint

curl -X POST "https://api.ittybit.com/webhooks/endpoints" \
-H "Authorization: Bearer ITTYBIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "url": "https://your-app.com/webhooks/ittybit",
  "topics": ["task.succeeded", "task.failed"]
}'

Webhook endpoint object

{
  "id": "we_abcdefgh12345678",
  "object": "webhook_endpoint",
  "url": "https://your-app.com/webhooks/ittybit",
  "topics": ["task.succeeded", "task.failed"],
  "status": "active",
  "created_at": 1735689825,
  "updated_at": 1735689825
}

Event topics

Subscribe to any combination of event topics when creating a webhook endpoint:

Topic	Description
`task.created`	A new task has been created
`task.updated`	A task's status or progress has changed
`task.succeeded`	A task completed successfully
`task.failed`	A task failed
`run.created`	A new run has been created
`run.updated`	A run's status or progress has changed
`run.succeeded`	All tasks in a run completed successfully
`run.failed`	One or more tasks in a run failed

Webhook delivery

When an event matching one of your subscribed topics occurs, Ittybit sends an HTTPS POST request to your endpoint URL with the event data:

{
  "id": "evt_abcdefgh12345678",
  "object": "event",
  "kind": "task.succeeded",
  "data": {
    "id": "task_abcdefgh12345678",
    "object": "task",
    "kind": "speech",
    "status": "succeeded",
    "outputs": [...]
  },
  "created_at": 1735689886
}

Handling webhooks

Your server should expose an endpoint that accepts POST requests and returns a 200 response promptly.

app.post("/webhooks/ittybit", async (req, res) => {
  const event = req.body;

  switch (event.kind) {
    case "task.succeeded":
      await handleTaskSuccess(event.data);
      break;
    case "task.failed":
      await handleTaskFailure(event.data);
      break;
  }

  res.status(200).send("OK");
});

Managing endpoints

List endpoints

curl "https://api.ittybit.com/webhooks/endpoints" \
-H "Authorization: Bearer ITTYBIT_API_KEY"

Update an endpoint

curl -X PATCH "https://api.ittybit.com/webhooks/endpoints/we_abcdefgh12345678" \
-H "Authorization: Bearer ITTYBIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "topics": ["task.succeeded", "task.failed", "run.succeeded"]
}'

Delete an endpoint

curl -X DELETE "https://api.ittybit.com/webhooks/endpoints/we_abcdefgh12345678" \
-H "Authorization: Bearer ITTYBIT_API_KEY"

Best practices

Use HTTPS — HTTP endpoints will be rejected.
Return 200 quickly — Your endpoint should respond within 5 seconds.
Log payloads — Store incoming payloads for debugging.
Handle retries — If your endpoint returns an error, Ittybit retries with exponential backoff.
Use specific topics — Only subscribe to the events you need.

API Reference

See the API Reference for the full list of webhook endpoint operations.

Webhooks

API Reference

On this page