External Events

1. Overview

External Events let external systems push facts into ResultFly so campaigns can react to purchases, loyalty changes, or back-office adjustments. This reference lists the transport details for v1. For the conceptual model, see Overview → External Events, Developers → External Events — Technical Overview, and Developers → State Model in ResultFly.

2. Authentication

All endpoints use server-to-server authentication (API keys or service credentials). Follow Integration Basics → Authentication for key provisioning and request signing.

3. Endpoints

3.1 `POST /v1/external-events`

Accepts a single external event.

Request body

Field	Type	Required	Description
`source`	string	✅	Event source identifier.
`external_event_id`	string	✅	Stable ID assigned by the source.
`type`	string	✅	Event type defined by the client.
`occurred_at`	ISO 8601 timestamp	❌	When the event happened; defaults to receipt time.
`identity`	IdentityRef object	✅	User identity; see Identity reference.
`attributes`	object	❌	Additional attributes consumed by campaign logic.

Behavior

If the (source, external_event_id) combination is new, the event is accepted and queued for processing.
If the combination already exists for this tenant, the event is acknowledged as a duplicate and no additional processing occurs.

Response examples


// Accepted
{
  "status": "accepted",
  "event_id": "evt_74d63a"
}


// Duplicate
{
  "status": "duplicate",
  "original_event_id": "evt_74d63a"
}

3.2 `POST /v1/external-events:batch`

Accepts multiple events in one request.

Request body

Field	Type	Required	Description
`items`	array of event objects	✅	Each item has the same fields as `POST /v1/external-events`.

Response example


{
  "results": [
    { "status": "accepted", "event_id": "evt_a" },
    { "status": "duplicate", "original_event_id": "evt_b" },
    { "status": "error", "error_code": "validation_failed", "message": "identity.type is missing" }
  ]
}

Each item is evaluated independently; duplicates and errors in one element do not block others.

4. Deduplication Semantics

ResultFly deduplicates external events per (tenant, source, external_event_id). Clients may safely retry submissions when they encounter network errors—the platform guarantees that duplicates will not re-apply business effects. This shield prevents accidental double rewards or repeated balance adjustments when files are resent or tasks are retried.

5. Error Handling

401 Unauthorized — authentication failed; verify API key or signature.
403 Forbidden — credentials lack access to the tenant or endpoint.
422 Unprocessable Entity — validation error (missing field, malformed identity).
5xx Server Error — transient issue; safe to retry with the same payload (deduplication protects against replays).