Webhooks

Outbound, signed HTTP callbacks for Responses. Browser jobs run 60–420s; polling GET /api/v1/responses/:id is fine for v0. At production scale, create with background: true (HTTP 202), do other work, and let Banana Peel POST when the run lands — especially response.requires_action, which is time-sensitive MFA / human input.

Webhooks are per account (the API key's workspace), not global. Manage them here or in Console → Webhooks. This is distinct from Stripe's inbound billing webhook.

Production recipe: 202 + webhook

# 1. Register the endpoint (once)
curl -s "$BANANA_PEEL_BASE/api/v1/webhooks" \
  -H "Authorization: Bearer $BANANA_PEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/webhooks/bananapeel"}'

# 2. Create in the background — do other work; we POST when the run lands
curl -s "$BANANA_PEEL_BASE/api/v1/responses" \
  -H "Authorization: Bearer $BANANA_PEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Prefer: respond-async" \
  -d '{
    "model": "banana-peel",
    "input": "Extract the title from https://example.com",
    "routing": "smart",
    "background": true
  }'
# → 202 { "id": "resp_…", "status": "in_progress" }

# 3. Your server receives:
# POST https://example.com/webhooks/bananapeel
# X-Banana-Peel-Signature: t=<unix>,v1=<hmac_sha256_hex>
# X-Banana-Peel-Event-Id: evt_…
# {
#   "id": "evt_…",
#   "object": "banana_peel.event",
#   "api_version": "2026-08-13",
#   "type": "response.completed",
#   "sequence": 1,
#   "created_at": "…",
#   "data": { /* GET /responses/:id */ }
# }

Register

POST /api/v1/webhooks — url required (public https; http://localhost is allowed only in local development and rejected in production). Optional events (defaults to every event type — the four response.* events and the five long_task.* events). Optional secret; if omitted, Banana Peel mints whsec_… and returns it once. List/get never include the secret. Rotate with POST /api/v1/webhooks/:id/rotate — the previous secret stays valid for 24 hours (old_secret_expires_at).

curl -s "$BANANA_PEEL_BASE/api/v1/webhooks" \
  -H "Authorization: Bearer $BANANA_PEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/bananapeel",
    "events": [
      "response.completed",
      "response.failed",
      "response.requires_action",
      "response.cancelled"
    ]
  }'
# → 201
# {
#   "id": "wh_…",
#   "object": "banana_peel.webhook",
#   "url": "https://example.com/webhooks/bananapeel",
#   "events": [ "response.completed", … ],
#   "disabled": false,
#   "secret": "whsec_…",          # shown once
#   "created_at": "2026-08-13T15:00:00.000Z"
# }

• GET /api/v1/webhooks / GET /api/v1/webhooks/:id
• PATCH /api/v1/webhooks/:id — url, events, enabled
• DELETE /api/v1/webhooks/:id
• GET /api/v1/webhooks/:id/deliveries / GET …/deliveries/:delivery_id / POST …/deliveries/:delivery_id/retry
• Ids from another account 404 (same as vault credentials).
• At most 25 endpoints per account (webhook_limit).

URL requirements (SSRF protection)

Endpoint URLs are validated twice: once at register/update time and again at every delivery, with DNS re-resolved on each attempt so a record that later points somewhere private stops receiving traffic. Failing URLs are rejected with invalid_webhook_url; failing deliveries record the reason on the delivery row.

• https:// required. http://localhost / 127.0.0.1 is a development-only carve-out — in production, localhost and loopback URLs are rejected.
• Hosts must resolve to public IPs. Private and reserved ranges (RFC1918, CGNAT, link-local), cloud-metadata addresses (169.254.169.254, metadata.google.internal), *.internal / *.local names, numeric (dword) hosts, and URLs with embedded credentials are rejected.
• Self-hosting? Set BP_ALLOW_LOCAL_WEBHOOKS=1 to opt out of the production localhost block (never set this on an internet-facing deployment).

Events

• response.completed — terminal success
• response.failed — failed / blocked / hard-TTL run_timeout
• response.cancelled — POST /api/v1/responses/:id/cancel
• response.requires_action — MFA / human input opened. Payload includes data.id and data.required_action (kind + prompt) so you can POST /api/v1/responses/:id/input. The secret the user will type is never included. May fire more than once per run (multiple MFA rounds).

Long tasks emitted their own event family. Multi-entity orchestration is disabled, so long_task.* events no longer fire — the types below remain valid subscription values (existing configurations keep validating) and are documented for reading historical deliveries. For all long_task.* events, data is the long-task object from GET /api/v1/long-tasks/:id (per-entity table, counts, gaps, budget, events) — same envelope, signature, and retry machinery as response.*; the long-task id takes the response-id slot in the envelope sequence.

• long_task.progress — fires per entity settle (delivered / retry / unfetchable / exhausted) and once when the manifest verifies. Repeating by design: one delivery per (entity, outcome), not one per task.
• long_task.interaction_required — a sub-task hit MFA and the task paused. data.interaction.run_id is the holding child run — answer via POST /api/v1/responses/:run_id/input. Fires once per holding run.
• long_task.completed / long_task.partial / long_task.failed — the terminal trio, once each per task. partial is first-class: some entities delivered; data.gaps lists exactly what did not, and why. There is no separate cancellation event type: a cancelled task arrives as long_task.failed with data.status: "cancelled" — read data.status, not just the event type, to distinguish.

if (alreadyProcessed(event.id)) return res.sendStatus(200);
enqueue(event);              // process async
markProcessed(event.id);
return res.sendStatus(200);  // Banana Peel waits up to 10 seconds

For response.* events, data is the same object as GET /api/v1/responses/:id, redacted (no secrets, no inline image bytes); long_task.* payloads are redacted the same way. Delivery is asynchronous — the run response is never delayed waiting on your endpoint. On brain-routed runs, response.completed / response.failed payloads therefore include data.banana_peel.routing_summary— runner, strategy, reason code, one redacted plain-words sentence, per-attempt fault attribution, policy version, widening echo, and the path to the full decision card — so "why was it routed there" arrives with the event instead of needing a second fetch. See Routing explanations.

Signature

Stripe-style HMAC. Headers: X-Banana-Peel-Signature: t=<unix>,v1=<hmac_sha256_hex> over {t}.{raw_body} using the endpoint secret. During the 24h rotation grace the header includes both signatures: t=…,v1=<new>,v1=<old> — verify against any v1. Also X-Banana-Peel-Event-Id, User-Agent: BananaPeel-Webhook/1.0. Reject deliveries older than ~5 minutes. Always verify against the raw body.

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

export function verifyBananaPeelSignature(secret, rawBody, header) {
  const v1s = [];
  let t;
  for (const part of header.split(',')) {
    const eq = part.indexOf('=');
    if (eq < 0) continue;
    const k = part.slice(0, eq).trim();
    const val = part.slice(eq + 1);
    if (k === 't') t = val;
    else if (k === 'v1') v1s.push(val);
  }
  if (!t || !v1s.length) return false;
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  const a = Buffer.from(expected);
  return v1s.some((v1) => {
    const b = Buffer.from(v1);
    return a.length === b.length && timingSafeEqual(a, b);
  });
}

// Express: app.post('/webhooks/bananapeel', express.raw({ type: 'application/json' }), (req, res) => {
//   const raw = req.body.toString('utf8');
//   if (!verifyBananaPeelSignature(process.env.BP_WEBHOOK_SECRET, raw, req.get('x-banana-peel-signature'))) {
//     return res.status(400).send('invalid signature');
//   }
//   const event = JSON.parse(raw);
//   if (alreadyProcessed(event.id)) return res.sendStatus(200);
//   enqueue(event);           // do not wait on work
//   markProcessed(event.id);
//   res.sendStatus(200);      // Banana Peel waits up to 10 seconds
// });

Acknowledge quickly

Banana Peel waits up to 10 seconds for a response. Verify the signature, enqueue the event, return 2xx. Do the real work asynchronously. Non-2xx (or a timeout) schedules a retry.

Retries

Success is HTTP 2xx. Terminal events (completed / failed / cancelled) retry with exponential backoff over ~24 hours: immediate, 5s, 30s, 2m, 10m, 30m, 2h, 8h, 24h. Due attempts are persisted (next_attempt_at) and swept by GET/POST /api/cron/webhooks (Bearer / x-cron-secret matching BP_CRON_SECRET) — also piggybacked on /api/cron/expire-artifacts. Cloud Run cannot sleep 24h in-process. If cron is not configured, listing webhooks still lazy-sweeps due retries for that account.

response.requires_action uses a short schedule (immediate, 5s, 15s, 30s, 1m, 2m) and stops retrying once the underlying MFA interaction is answered or expired — delivering it after the window is useless.

Duplicate terminal writes do not double-notify (one event per webhook + response + type; repeating types add a discriminator — MFA rounds the interaction id, long_task.progress the entity + outcome, long_task.interaction_required the holding run id). After 20 consecutive exhausted deliveries the endpoint is auto-disabled — re-enable with PATCH … { "enabled": true } or Console → Webhooks. Manual redelivery: POST /api/v1/webhooks/:id/deliveries/:delivery_id/retry (same event.id).

Polling still works. Prefer webhooks when you cannot hold a 60–420s socket or need MFA without spinning GET. See Create a response.