Process and reconcile events

Sparkles emits an ordered event stream for each API access grant. Webhooks carry one event per request; the event feed returns the same durable events for gap recovery.

Event envelope

Every durable event contains:

Field	Type	Description
`id`	UUID	Stable across webhook retries and event-feed reconciliation.
`sequence`	Positive integer	Monotonically increasing cursor within the access grant.
`type`	String	One of the event types below.
`data`	Object	Event-specific payload.
`createdAt`	ISO 8601 string	When Sparkles recorded the event.

Process events in numeric sequence order and deduplicate on id.

Credit claim events

credit_claim.created fires after Sparkles creates and reserves a unique claim. Its status is pending and claimedAt is null. credit_claim.claimed fires after Sparkles adds the credits once to the recipient’s selected organization. Its status is claimed and claimedAt contains an ISO 8601 timestamp. Both payloads contain:

Field	Type
`claimId`	UUID
`leadId`	String
`variant`	String
`creditAmount`	Positive whole-credit integer
`status`	`pending` or `claimed`
`createdAt`	ISO 8601 string
`claimedAt`	ISO 8601 string or `null`

Attributed lifecycle events

All lifecycle payloads contain claimId, leadId, variant, and occurredAt.

Event	Additional fields	Fires when
`project.connected`	`projectId`	The attributed recipient connects a new repository-backed project after claiming the offer.
`task.started`	`taskId`, `projectId` or `null`	Sparkles accepts and durably creates the recipient’s cloud task. The agent runtime may still be starting.
`pull_request.opened`	`pullRequestId`, `taskId`, `projectId` or `null`	Sparkles durably records an opened pull request for the attributed task.
`conversion.paid`	`conversionId`	The attributed organization completes its first positive initial subscription invoice. Renewals do not emit it.

Attribution is immutable first touch. Project, task, and pull-request events use the first claimed offer for the exact recipient and selected organization. Paid conversion uses the first claimed offer for the selected organization. Redeeming a later claim does not replace either attribution.

Recover a sequence gap

Use the event feed only for backfills or webhook gap recovery:

curl "https://sparkles.dev/api/public/v1/events?after=41&limit=100" \
  --header "Authorization: Bearer $SPARKLES_API_KEY"

{
	"data": [
		{
			"id": "06ea989d-3980-4f83-bb58-93ad29ae8409",
			"sequence": 42,
			"type": "project.connected",
			"data": {
				"claimId": "01890a5d-ac96-774b-bcce-b302099a8057",
				"leadId": "lead_123",
				"variant": "call-offer",
				"projectId": "aaf58b9e-a967-4fde-a82f-e7d574e11a6a",
				"occurredAt": "2026-08-03T10:12:00.000Z"
			},
			"createdAt": "2026-08-03T10:12:00.000Z"
		}
	],
	"nextCursor": 42
}

Save nextCursor only after processing every returned event successfully, then pass it as the next after value. The default and maximum limit is 100. An empty page preserves the supplied cursor.

Recovery loop

Read your last durable cursor.
Request events with after=<cursor>.
Process each event in ascending sequence order.
Deduplicate each event by UUID.
Save nextCursor after the batch commits.
Repeat until data is empty.

See error handling for rate-limit and retry behavior.

Get started

Integration guides

API reference

Process and reconcile events

Event envelope

Credit claim events

Attributed lifecycle events

Recover a sequence gap

Recovery loop

​Event envelope

​Credit claim events

​Attributed lifecycle events

​Recover a sequence gap

​Recovery loop

Event envelope

Credit claim events

Attributed lifecycle events

Recover a sequence gap

Recovery loop