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 pull. One event per successful API call, regardless of how many ids were in the request body. The data.unit field tells you which kind of pull fired the event:

unit: "property" — fired by POST /materials/:id/properties/pull or GraphQL pullProperties. Payload carries data.materialId and data.propertyIds.
unit: "process" — fired by POST /processes/:id/pull or GraphQL pullProcess (batch-size pull). Payload carries data.processId, data.referenceProductIds, and data.revealedCount.
unit: "impact" — fired by POST /processes/:id/impacts/pull or GraphQL pullImpacts (per-characterization-method pull). Payload carries data.processId and data.characterizationFactorIds.

{
  "id": "evt_8f3c5d9a-…",
  "type": "datapoint.pulled",
  "created": 1747000800,
  "livemode": true,
  "teamId": "4b6f9c28-…",
  "data": {
    "unit": "property",
    "materialId": "8c2a17a4-1234-4d1e-9b21-3a8e2c91c0a1",
    "propertyIds": ["55ada…", "18a58…"],
    "userId": "u_a13c…"
  }
}

{
  "id": "evt_b1f04e7a-…",
  "type": "datapoint.pulled",
  "created": 1747000801,
  "livemode": true,
  "teamId": "4b6f9c28-…",
  "data": {
    "unit": "process",
    "processId": "bfffd26f-aa46-42ab-9069-e07102b06c4d",
    "referenceProductIds": ["f5651ee4-1234-4d1e-9b21-3a8e2c91c0a1"],
    "revealedCount": 1,
    "userId": "u_a13c…"
  }
}

{
  "id": "evt_c2g15f8b-…",
  "type": "datapoint.pulled",
  "created": 1747000802,
  "livemode": true,
  "teamId": "4b6f9c28-…",
  "data": {
    "unit": "impact",
    "processId": "340e4939-6d75-430c-b6c7-1e98d566afdd",
    "characterizationFactorIds": [
      "dbc5a15e-e65f-4834-85a6-b9d9940f0a67,340e4939-6d75-430c-b6c7-1e98d566afdd"
    ],
    "userId": "u_a13c…"
  }
}

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."
  }
}