Send events

A Reconify sender does three things: it posts batches of events, it reads every item result, and it retries without creating duplicate evidence. This guide covers all three with a write or admin key, which you create in Authentication.

Anatomy of an event

An event answers four questions at once: which journey it belongs to, what happened, which operation it is part of, and which entity the money moves toward. Everything else is context that makes the evaluation sharper.

The fields you send

Field	When you use it	Type	Values
`flow`	Always. It selects the expected sequence and deadlines, and it derives the entity type, so no separate entity-type field exists.	string	`payment_to_wallet`, `payment_to_order`, `wallet_to_wallet`, `wallet_to_payout`
`type`	Always. It says what happened, and the flow decides which types belong to it.	string	`payment.initiated`, `payment.succeeded`, `payment.failed`, `order.fulfilled`, `wallet.credited`, `wallet.debited`, `wallet.refunded`, `payout.initiated`, `payout.succeeded`, `payout.failed`
`reference`	Always. Events sharing a reference become one operation, which is what lets Reconify notice a missing step.	string	Any non-empty string from your system, such as `order-123`, identical across the operation’s events.
`entity_id`	Always. It names the wallet, order, or participant whose outcome is being verified.	string	Any non-empty string, such as `wallet_123`. The flow decides whether Reconify reads it as a wallet or an order.
`amount`	On every monetary type. `payment.failed` and `payout.failed` are the two exceptions.	string	A decimal string such as `"150.00"`. A number or a float is rejected.
`currency`	Alongside `amount`. Targets are tracked per currency, so one wallet in two currencies is two positions.	string	Three-letter uppercase ISO code, such as `USD` or `XOF`.
`id`	Whenever your source system has a stable identifier. It makes an exact retry return `duplicate` instead of storing a second copy.	string	`evt_` followed by 26 uppercase alphanumeric characters, derived from your source record.
`occurred_at`	Whenever the source knows when the event happened. Deadlines run on this value, not on delivery time.	string	RFC 3339 UTC, such as `2026-01-01T12:00:00Z`.
`correlation_id`	When one business transaction spans several services and produces several operations.	string	1 to 200 visible ASCII characters, opaque, carrying no personal data; producer-supplied. See Trace a flow across services.
`causation_id`	When this event happened because of one earlier event.	string	That earlier event’s opaque `id`, 1 to 200 visible ASCII characters; producer-supplied or upstream. See Trace a flow across services.
`metadata`	For your own context that Reconify keeps but does not evaluate.	object	Flat, at most 20 keys, values of string, number, or boolean. Strings cap at 500 characters.
`data`	For provider, failure, and retry context.	object	See the table below.

Two of those fields fill themselves in when you leave them out, and the result says so through a warnings entry. An absent id receives a generated one, marked id_generated, and an absent occurred_at defaults to the receipt time, marked occurred_at_generated. Both defaults cost you something: a generated ID makes the event unsafe to retry, and a defaulted timestamp measures deadlines from when the request arrived rather than from when the money moved. The contract rejects any field it does not define, which is why source-only context goes into metadata or data rather than onto the event itself.

Metadata and personal data

Reconify retains event metadata as evidence. Use it for opaque internal identifiers and operational context that does not identify a person. Do not send names, email addresses, phone numbers, postal addresses, or other personal data in metadata.

An identifier is not automatically anonymous because it is hashed. Use a stable internal identifier that does not reveal a person and cannot be derived from their contact details.

For example, an internal customer ID is suitable metadata:

Compliant metadata

{
  "metadata": {
    "customer_id": "cus_01J3Y0M8VJQ5W1R3E4J4K7N8P9",
    "checkout_channel": "mobile"
  }
}

An email address is personal data and must not be sent:

Non-compliant metadata

{
  "metadata": {
    "customer_email": "customer@example.com"
  }
}

The same rule applies whether you call POST /v2/events directly or use client.ingestion.ingestMonitoringEvents in the TypeScript SDK. Keep the lookup from your opaque ID to the person in your own authorized system.

The `data` object

data carries what a provider or a failure knows about the event.

Field	When you use it	Type
`integration_ref`	On `payment.initiated`, to ask Reconify to check the payment with the provider itself.	string
`provider_transaction_id`	With `integration_ref`, as the value Reconify looks up. Numeric IDs travel as strings.	string
`provider_reference`	With `integration_ref`, where the adapter supports reference lookup instead.	string
`provider`	As descriptive context. It selects nothing and calls nothing.	string
`failure_code`	On a failed event, as the stable code your system or the provider returned.	string
`failure_message`	On a failed event, as the human-readable reason.	string
`retryable`	On a failed event, when your system knows whether a retry makes sense.	boolean

Enrich events with provider data covers the integration side of those provider fields.

The event a read returns

A read returns the normalized event, which is not identical to what you sent. Some values come from you, some Reconify derives, and some Reconify observes.

Field	What it holds	Who supplies it
`id`	The event identifier.	You, through `id`. Reconify generates one otherwise.
`flow`	The monitored flow.	You.
`event_type`	What happened. Note the rename: requests send `type`, reads return `event_type`.	You.
`reference`	The operation reference.	You.
`entity_id`	The target identifier.	You.
`entity_type`	`wallet` or `order`.	Reconify, derived from the flow.
`amount`	The normalized decimal amount, or `null`.	You.
`currency`	The ISO currency code, or `null`.	You.
`provider`	The related provider name, or `null`.	You, through `data.provider`.
`occurred_at`	When the source event happened.	You, or the receipt time when you omit it.
`received_at`	When Reconify received the event.	Reconify.
`status`	The processing state: `received`, `published`, `processed`, or `failed`.	Reconify.

Send one event

The smallest useful request carries a single event in the events array:

curl --fail-with-body -sS -X POST "https://api.reconifyhq.com/v2/events" \
  -H "Authorization: Bearer $RECONIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":"evt_01J3Y0M8VJQ5W1R3E4J4K7N8W5","flow":"payment_to_wallet","type":"payment.succeeded","occurred_at":"2026-01-01T12:00:00Z","amount":"150.00","currency":"USD","reference":"order-123","entity_id":"wallet_123","data":{"provider":"stripe","provider_reference":"pi_123"}}'

import { ReconifyClient } from "@reconifyhq/sdk";

const client = new ReconifyClient({ apiKey: process.env.RECONIFY_API_KEY });

const result = await client.ingestion.ingestMonitoringEvents({
  body: {
    events: [
      {
        id: "evt_01J3Y0M8VJQ5W1R3E4J4K7N8W5",
        flow: "payment_to_wallet",
        type: "payment.succeeded",
        occurred_at: "2026-01-01T12:00:00Z",
        amount: "150.00",
        currency: "USD",
        reference: "order-123",
        entity_id: "wallet_123",
        data: { provider: "stripe", provider_reference: "pi_123" },
      },
    ],
  },
});

from reconify import Reconify
from reconify.models import (
    MonitoringBatchRequest,
    MonitoringEvent,
    MonitoringEventData,
)

with Reconify() as client:
    result = client.ingestion.ingest_monitoring_events(
        MonitoringBatchRequest(
            events=[
                MonitoringEvent(
                    id="evt_01J3Y0M8VJQ5W1R3E4J4K7N8W5",
                    flow="payment_to_wallet",
                    type="payment.succeeded",
                    occurred_at="2026-01-01T12:00:00Z",
                    amount="150.00",
                    currency="USD",
                    reference="order-123",
                    entity_id="wallet_123",
                    data=MonitoringEventData(
                        provider="stripe", provider_reference="pi_123"
                    ),
                )
            ]
        )
    )

Send a batch

One request carries 1 to 500 events, and the response keeps the order you sent them. Two events that share a reference belong to the same operation, so a batch often carries a whole flow:

cURL

curl --fail-with-body -sS -X POST "https://api.reconifyhq.com/v2/events" \
  -H "Authorization: Bearer $RECONIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {"id":"evt_01J3Y0M8VJQ5W1R3E4J4K7N8X6","flow":"payment_to_wallet","type":"payment.succeeded","amount":"150.00","currency":"USD","reference":"order-123","entity_id":"wallet_123"},
    {"id":"evt_01J3Y0M8VJQ5W1R3E4J4K7N8Y7","flow":"payment_to_wallet","type":"wallet.credited","amount":"150.00","currency":"USD","reference":"order-123","entity_id":"wallet_123"}
  ]'

Limits and pagination covers the body and event size bounds.

Read every result

Reconify validates each item independently, so every event comes back with one of three outcomes:

accepted means Reconify stored the event.
duplicate means the same event ID and content were already stored.
rejected means Reconify stored nothing, and code, field, and message explain why.

An HTTP 202 covers a mixed batch. A batch where every item fails returns 422. Because of that, the status alone never tells you what landed, and your handler reads the results array:

for (const item of result.results) {
  if (item.status === "rejected") {
    logger.error("event rejected", {
      index: item.index,
      code: item.code,
      field: item.field,
      message: item.message,
    });
  }
}

for item in result.results:
    if item.status == "rejected":
        logger.error(
            "event rejected",
            extra={
                "index": item.index,
                "code": item.code,
                "field": item.field,
                "message": item.message,
            },
        )

The index locates the item in the array you submitted, which keeps the customer reference out of your logs. Each code points at one fix:

`code`	Meaning
`invalid_event`	A field failed validation. Read `field`.
`unknown_field`	The event carried a field the contract does not define.
`idempotency_conflict`	The `id` was reused with different content. Investigate before any retry.
`duplicate`	Reconify already stored this event. Treat it as delivered.
`malformed_request`	The request body could not be parsed.

Retry safely

A retry that reuses the same event IDs and the same payloads is safe. Reconify answers duplicate for anything it stored before the retry, and duplicate counts as delivered. Reusing an ID with different content returns idempotency_conflict, which signals a producer bug rather than a delivery problem. Events without an id receive a generated one, so Reconify cannot recognize their replay. Those events are unsafe to retry. Both SDKs retry reads automatically and leave ingestion alone by default, because a batch without stable IDs cannot be replayed safely. Ingestion retries become an option once every event carries an id:

const result = await client.ingestion.ingestMonitoringEvents({
  body: batch,
  request: { retry: { retryNonIdempotent: true } },
});

from reconify.transport import RetryConfig

client = Reconify(retry=RetryConfig(max_retries=2, retry_unsafe_methods=True))

The full policy lives in TypeScript errors and retries and Python errors and retries.

Verify what arrived

A read or admin key lists events or fetches one by ID, which is how you confirm that your sender works end to end:

curl --fail-with-body -sS "https://api.reconifyhq.com/v2/events?limit=25" \
  -H "Authorization: Bearer $RECONIFY_READ_KEY"

const page = await client.events.listEvents({ query: { limit: 25 } });

page = client.events.list_events(limit=25)

The response carries the normalized event from the anatomy above. Four of its fields confirm the flow landed as intended: reference matches what you sent, event_type matches your type, entity_type reads as the flow implies, and status reaches processed once evaluation finishes. received and published are normal in the seconds after ingestion. A status that stays there for minutes belongs in Troubleshooting. Sending the identical batch a second time closes the loop on retry safety, because every item comes back as duplicate. An idempotency_conflict there means the payload changed between the two attempts.

What comes next

Four pages continue from a working sender.

TypeScript

Send event batches with the TypeScript SDK.

Python

Send event batches with the Python SDK.

Trace across services

Link one transaction that spans several services.

Go live

Check the integration before and after launch.

Getting started

Start monitoring

Understand monitoring

Troubleshoot and support

Agent tooling

Examples

Anatomy of an event

The fields you send

Metadata and personal data

The `data` object

The event a read returns

Send one event

Send a batch

Read every result

Retry safely

Verify what arrived

What comes next

TypeScript

Python

Trace across services

Go live

​Anatomy of an event

​The fields you send

​Metadata and personal data

​The data object

​The event a read returns

​Send one event

​Send a batch

​Read every result

​Retry safely

​Verify what arrived

​What comes next

TypeScript

Python

Trace across services

Go live

Anatomy of an event

The fields you send

Metadata and personal data

The `data` object

The event a read returns

Send one event

Send a batch

Read every result

Retry safely

Verify what arrived

What comes next