Webhooks for tool calls

​

Ask for a webhook

curl -s -X POST "https://conigma-tool-server-production.up.railway.app/api/tool/instagram-profiles-collect-by-url" \
  -H "Authorization: Bearer $CONNIE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f6c2a40-9b1e-4f55-8a5e-1c2d3e4f5a6b" \
  -d '{"input": {"url": "https://www.instagram.com/nasa"}, "webhook": "https://example.com/connie-webhook"}'

• The URL must use https, contain no username or password and be at most 2,048 characters. Otherwise the call is refused with 400 invalid_webhook and nothing runs.
• Connie looks up the URL’s host when it accepts the call. A host on a private network, or one with no DNS address, is refused with 400 invalid_webhook and nothing runs; send the corrected call with a new Idempotency-Key. If the lookup fails for a moment, the call answers 503 webhooks_unavailable and nothing runs: send the same request again.
• The webhook is part of the request: sending the same Idempotency-Key with a different webhook (or none) is 409 idempotency_conflict.
• You can still poll the operation as usual. A successful call that ends within 25 seconds answers 200 with its outcome and also sends the webhook. A failed call returns its error status and sends the corresponding outcome.

​

What Connie sends

{
  "id": "0b9e7c1e-6f0d-4c55-9b0a-2d0c1a4f8e21",
  "type": "tool_invocation.completed",
  "createdAt": "2026-10-12T09:41:07.000Z",
  "data": {
    "invocationId": "7c0e5a52-1f7a-4e0e-9a51-0d6b2f7d1c11",
    "toolId": "instagram-profiles-collect-by-url",
    "status": "completed",
    "ok": true,
    "result": { "...": "the tool's output" },
    "billing": { "chargedCredits": 1, "items": [ { "toolId": "instagram-profiles-collect-by-url", "summary": "…", "chargedCredits": 1, "status": "charged" } ] }
  }
}

​

Verify the signature

curl -s "https://conigma-tool-server-production.up.railway.app/api/tool-webhooks/secret" -H "Authorization: Bearer $CONNIE_API_KEY"
# {"secret":"whsec_…"}

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

/** True when the webhook came from Connie. `rawBody` is the exact request body string. */
export function verifyConnieWebhook(rawBody, headers, secret) {
  const id = headers['webhook-id'], timestamp = headers['webhook-timestamp'], header = headers['webhook-signature'];
  if (!id || !timestamp || !header) return false;
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64');
  const expected = createHmac('sha256', key).update(`${id}.${timestamp}.${rawBody}`).digest();
  return header.split(' ').some((part) => {
    const [version, signature] = part.split(',');
    const given = Buffer.from(signature ?? '', 'base64');
    return version === 'v1' && given.length === expected.length && timingSafeEqual(given, expected);
  });
}

import base64, hashlib, hmac, time

def verify_connie_webhook(raw_body: bytes, headers, secret: str) -> bool:
    """True when the webhook came from Connie. `raw_body` is the exact request body."""
    msg_id, timestamp, header = headers.get("webhook-id"), headers.get("webhook-timestamp"), headers.get("webhook-signature")
    if not (msg_id and timestamp and header):
        return False
    if abs(time.time() - int(timestamp)) > 300:
        return False
    key = base64.b64decode(secret.removeprefix("whsec_"))
    expected = base64.b64encode(hmac.new(key, f"{msg_id}.{timestamp}.".encode() + raw_body, hashlib.sha256).digest()).decode()
    return any(hmac.compare_digest(part, f"v1,{expected}") for part in header.split(" "))

​

Answer quickly, handle duplicates

• Answer with any 2xx within 10 seconds, then do the work. Connie doesn’t read the body.
• Retries: any other answer, a timeout or a connection error is retried after 30 seconds, 2 minutes, 10 minutes, 30 minutes, 1 hour, 2 hours, 4 hours and 8 hours (about 16 hours in all). Answer 410 Gone to stop retries for that event.
• Redirects are not followed. Give Connie the final URL.
• A host that can’t be looked up is retried on the same schedule. Connie stops for good only if the host now points to a private network.
• Duplicates happen. The same event can arrive more than once: skip a webhook-id you have already handled.
• Order isn’t guaranteed between different calls. For one call, the event’s data is its final outcome. If a call that only reads was interrupted and ran again, you may get an unknown_outcome event first and then, with a new webhook-id, the real outcome.

​

Rotate the secret

curl -s -X POST "https://conigma-tool-server-production.up.railway.app/api/tool-webhooks/secret/rotate" -H "Authorization: Bearer $CONNIE_API_KEY"
# {"secret":"whsec_new…","previousSecretValidUntil":"2026-10-13T09:41:07.000Z"}

​

Related

• Tool API
• Webhook reference
• Errors and limits