Need to manage API keys, view logs, or check usage?Open the Developer portal →

Webhooks

Receive signed HTTPS events from Circa in real time when things happen on your account.

Register an endpoint, pick the events it should receive, and Circa POSTs a JSON payload with a signature header whenever one of those events fires for your team. Every endpoint is scoped to a single team and managed from the Developer portal → Webhooks tab.

The lifecycle

  1. Open the portal's Webhooks tab and click Add endpoint. Provide your URL, optional description, and tick the event types you want.
  2. Circa returns a signing secret (whsec_…) exactly once — copy it into your secret manager.
  3. Whenever a matching event fires for your team, Circa POSTs JSON to your URL with headers like Circa-Signature: t=…,v1=….
  4. Your server verifies the signature with the secret (see Verifying signatures), processes the event, and responds 2xx within 15 seconds.
  5. Non-2xx responses are retried with exponential backoff (30s, 2m, 10m, 1h, 6h, 24h, then dropped). After 20 consecutive failures the endpoint is auto-disabled — re-enable it from the portal.

Example payload

{
  "id": "evt_8f3c5d9a-…",
  "type": "datapoint.pulled",
  "created": 1747000800,
  "livemode": true,
  "teamId": "4b6f9c28-6f4e-4e7f-a36d-2ff989045d10",
  "data": {
    "materialIds": ["m_8c2…", "m_a4d…"],
    "userId": "u_a13c…",
    "creditsDebited": 2
  }
}

Headers Circa sends

POST /your-webhook HTTP/1.1
Host: yourapp.example.com
Content-Type: application/json
User-Agent: Circa-Webhooks/1.0
Circa-Event: datapoint.pulled
Circa-Event-Id: evt_8f3c5d9a-…
Circa-Webhook-Id: wh_…
Circa-Signature: t=1747000800,v1=8e4dbf…
ℹ
Always verify Circa-Signature before trusting the payload — see Verifying signatures.

Idempotency

Each delivery carries a stable Circa-Event-Id. Treat it as an idempotency key on your side — if you see the same id twice, drop the second copy. Retries always reuse the same id.

Testing

Every endpoint has a Send test button in the portal. It fires a synthetic webhook.testevent with the same signing path as production events, so it's the quickest way to confirm your signature check works end-to-end.

Next steps