Webhook events

Every event type Circa can deliver, when it fires, and the shape of its data payload.

All event payloads share a common envelope:

{
  "id": "evt_<uuid>",        // stable identifier — use as idempotency key
  "type": "<event-type>",    // e.g. "datapoint.pulled"
  "created": 1747000800,     // unix seconds
  "livemode": true,          // false for events from circa_test_ keys
  "teamId": "4b6f9c28-…",    // team the event belongs to
  "data": { /* event-specific */ }
}

datapoint.pulled

Fires after a successful POST /datapoints/pull (or the equivalent GraphQL pullDatapoints mutation). One event per successful API call, regardless of how many material ids were in the request body.

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

webhook.test

Fires when an operator clicks Send test on the endpoint row in the portal. Use it to validate your signature check without touching billable endpoints.

{
  "id": "evt_3a1f9c0b-…",
  "type": "webhook.test",
  "created": 1747000800,
  "livemode": false,
  "teamId": "4b6f9c28-…",
  "data": {
    "message": "This is a test event triggered from the developer portal."
  }
}