Webhooks

instabox webhooks create https://example.com/hook --event sandbox.started --event sandbox.error
instabox webhooks ls
instabox webhooks test wh_...
instabox webhooks deliveries wh_...

curl -X POST https://api.instabox.sh/v1/orgs/$ORG/webhooks -H "Authorization: Bearer $INSTABOX_API_KEY" \
  -H 'Content-Type: application/json' -d '{"url":"https://example.com/hook","events":["sandbox.started","sandbox.error"]}'

• Without --event, the endpoint subscribes to every type. The types are under Reference.
• create and rotate print the signing secret (whsec_…) once.
• The URL must be public https. Redirects are not followed.
• The dashboard’s Webhooks page does the same, with a delivery log.

​

Verify the signature

import crypto from 'node:crypto';
const key = Buffer.from(secret.slice('whsec_'.length), 'base64');
const want = crypto.createHmac('sha256', key).update(`${id}.${timestamp}.${rawBody}`).digest();
const ok = header.split(' ').some((s) => {
  const got = Buffer.from(s.startsWith('v1,') ? s.slice(3) : '', 'base64');
  return got.length === want.length && crypto.timingSafeEqual(got, want); // constant time
});

​

Answer each delivery in time

• Order: one machine’s events arrive in order, also across retries. A later event waits while an earlier one is retried. Events of different machines interleave, so order those by createdAt.
• Retries: any other answer, and a timeout, is retried after 5 s, 5 min, 30 min, 2 h, 5 h, 10 h, and 10 h. Then the delivery fails. A delivery still pending 3 days after its event fails as expired. instabox webhooks retry sends a finished one again.
• Log: deliveries are kept 30 days.

​

Reference

​

Events

​

Event body

{
  "id": "evt_…",
  "type": "sandbox.suspended",
  "createdAt": "…",
  "orgId": "org_…",
  "data": {
    "sandbox": { "id": "m_…", "name": "worker-1", "metadata": {} },
    "previousState": "suspending",
    "state": "suspended",
    "reason": "idle",
    "operationId": "op_…"
  }
}