Webhooks - jinba

Overview

Webhooks allow you to receive HTTP notifications whenever significant events occur in your organization. Instead of polling the API, you register a URL and Jinba Toolbox pushes event payloads to it in real time. Webhooks are configured per organization (by Owners and Admins) and can subscribe to one or more event types.

Event Types

Event	Description
`tool.run.completed`	A tool execution finished successfully
`tool.run.failed`	A tool execution failed
`toolset.published`	A new toolset version was published

Run events are dispatched for executions through the organization run endpoint (POST /v1/orgs/:orgId/toolsets/:slug/tools/:toolSlug/run, which the SDK’s run() uses). Test runs, public-endpoint runs and MCP calls do not trigger webhooks.

Setting Up Webhooks

Create a webhook endpoint

Set up an HTTP endpoint on your server that can receive POST requests. The endpoint must return a 2xx status code to acknowledge receipt.

Use the API or the web console (Webhooks in the organization sidebar, Create Webhook) to register your endpoint URL and select the events you want to subscribe to. Registering and testing need an Owner or Admin session token; an API key (Member level) gets 403.

curl -X POST https://toolbox-api.jinba.io/v1/orgs/{orgId}/webhooks \
  -H "Authorization: Bearer <JinbaAuth session token>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/jinba",
    "events": ["tool.run.completed", "tool.run.failed"]
  }'

Store the signing secret

When you create a webhook, a signing secret is generated and returned once in the creation response (the console shows it in the Webhook Created dialog). Store it securely — you will use it to verify incoming payloads. Later reads only return a secretPreview.

Send a test event

Verify your endpoint is working by sending a test event (the console has a play button per webhook). The test payload is a tool.run.completed event with data: { "test": true, "message": "This is a test webhook delivery" }:

curl -X POST https://toolbox-api.jinba.io/v1/orgs/{orgId}/webhooks/{webhookId}/test \
  -H "Authorization: Bearer <JinbaAuth session token>"

Webhook Configuration

Each webhook has the following properties:

interface Webhook {
  id: string;
  organizationId: string;
  url: string;           // Destination URL
  events: string[];      // Subscribed event types
  secret: string;        // HMAC signing secret (returned on creation only)
  enabled: boolean;      // Whether the webhook is active
  createdAt: Date;
  updatedAt: Date;
}

Payload Format

Every webhook delivery is an HTTP POST with Content-Type: application/json, an X-Webhook-Event header carrying the event name, an X-Webhook-Signature header (see below) and a JSON payload with the following structure:

{
  "event": "tool.run.completed",
  "timestamp": "2026-02-01T12:00:00.000Z",
  "data": {
    "runId": "run_abc123",
    "toolSetSlug": "slack-tools",
    "toolSlug": "post-message",
    "status": "success",
    "durationMs": 1234
  }
}

Event-Specific Payloads

tool.run.completed

{
  "event": "tool.run.completed",
  "timestamp": "2026-02-01T12:00:00.000Z",
  "data": {
    "runId": "run_abc123",
    "toolSetSlug": "slack-tools",
    "toolSlug": "post-message",
    "status": "success",
    "durationMs": 1234
  }
}

tool.run.failed

{
  "event": "tool.run.failed",
  "timestamp": "2026-02-01T12:05:00.000Z",
  "data": {
    "runId": "run_def456",
    "toolSetSlug": "slack-tools",
    "toolSlug": "post-message",
    "status": "failed",
    "error": "channel_not_found",
    "durationMs": 567
  }
}

error is the error message string. toolset.published

{
  "event": "toolset.published",
  "timestamp": "2026-02-01T10:00:00.000Z",
  "data": {
    "toolSetSlug": "slack-tools",
    "version": "1.3.0",
    "toolCount": 4,
    "releaseNotes": "Added thread reply support"
  }
}

Signature Verification

Every webhook request includes an X-Webhook-Signature header containing an HMAC-SHA256 signature of the request body, computed with your webhook’s signing secret.

X-Webhook-Signature: sha256=a1b2c3d4e5f6...

Verify the signature on your server to ensure payloads have not been tampered with:

import { createHmac, timingSafeEqual } from "node:crypto";

function verifyWebhookSignature(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const expected = "sha256=" + createHmac("sha256", secret)
    .update(payload)
    .digest("hex");

  return timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// In your request handler
const isValid = verifyWebhookSignature(
  requestBody,
  request.headers["x-webhook-signature"],
  process.env.WEBHOOK_SECRET!
);

if (!isValid) {
  return new Response("Invalid signature", { status: 401 });
}

Webhook Management API

Method	Endpoint	Description
GET	`/v1/orgs/:orgId/webhooks`	List webhooks
POST	`/v1/orgs/:orgId/webhooks`	Create webhook (`url`, `events`); returns the `secret`
GET	`/v1/orgs/:orgId/webhooks/:webhookId`	Get webhook
PATCH	`/v1/orgs/:orgId/webhooks/:webhookId`	Update webhook (`url`, `events`, `enabled`)
DELETE	`/v1/orgs/:orgId/webhooks/:webhookId`	Delete webhook
POST	`/v1/orgs/:orgId/webhooks/:webhookId/test`	Send test event; responds `502` if your endpoint does not answer `2xx`

Creating, updating, deleting and testing webhooks requires the Owner or Admin role; API keys (Member level) can only list them.

Delivery and Retry Behavior

Each delivery waits up to 10 seconds for a response. A 2xx status code counts as success. If your endpoint does not return 2xx, the delivery is recorded as failed with a retry time (1 minute, then 5 minutes, at most 3 attempts), but no background job currently processes those retries, so in practice each event is delivered once. Treat a failed delivery as lost and reconcile from the Runs page or API if you need it. The webhook itself is never disabled automatically; you can enable or disable it with the Active / Disabled toggle in the console or via PATCH with enabled.

Best Practices

Always verify the signature before processing a payload to prevent tampering.
Return a 200 status quickly — perform any heavy processing asynchronously after acknowledging the webhook.
Use idempotent processing — webhook deliveries may arrive more than once due to retries. Use the runId or event timestamp to deduplicate.
Monitor webhook health — use the test button to verify endpoints and investigate delivery failures.
Subscribe only to needed events — reduce noise by selecting only the events your integration requires.

REST API — Full endpoint reference
Security & Access Control — Authentication and authorization details

​Overview

​Event Types

​Setting Up Webhooks

​Webhook Configuration

​Payload Format

​Event-Specific Payloads

​Signature Verification

​Webhook Management API

​Delivery and Retry Behavior

​Best Practices

​Related