Protocols1 min read

Protocols — Overview

Four ways events reach Aforo beyond HTTP. MCP for AI tool calls, Agentic APIs for autonomous workflows, Webhook Ingestion for third-party push, Batch Upload for historical data.

Docs  Protocols  Overview

Aforo's baseline ingest is HTTP — gateways send events, SDKs send events, the public meter endpoint takes events. These four pages cover the other shapes: MCP tool calls, agent workflows, third-party webhooks pushing into you, and backfill from CSV / NDJSON files. Same downstream pipeline; different shape going in.

What this section is for#

It documents the ingest surfaces that aren't a plain SDK call or a gateway plugin. Each protocol has its own shape, its own authentication wrinkle, and its own metering envelope — but once an event is in Aforo, every downstream stage (catalog lookup, rate plan application, invoice generation, analytics rollup) is identical.

Pages in this section#

Pick by what you are metering#

You are meteringUseWhy this one

MCP tool calls from Claude / your agent runtimePer-tool pricing, session lifetime, no per-request HTTP overhead.

A LangChain / CrewAI / AutoGen autonomous workflowTrace-level events with step + token attribution.

A third-party SaaS that already knows usage (Stripe, Twilio, SendGrid)Skip the SDK install — point their webhook at our receiver.

A year of historical logs from a legacy systemBulk path with idempotency and a validation report.

A request through your own API gatewayGateway plugin (not this section)See the Gateways section — zero-code metering at the edge.

A custom event from your own backend serviceSDK (not this section)See the SDKs section — Node, Python, Go, Java.

Common shape across all four#

However the event arrives, the downstream pipeline reads it as four required fields plus optional metadata:

FieldWhat it is

customerIdWho the event bills against. Required.

metricNameWhich billable unit (from your catalog). Required. Rejected if it does not exist in the tenant.

quantityHow much. Required, must be ≥ 0.

occurredAtWhen it happened, ISO-8601. Optional — defaults to now. Up to 5 min in the future, up to 90 days in the past.

metadataArbitrary JSON. Used by filter conditions, COGS attribution, and downstream analytics.

 INFO

The ingestor rejects events with unknown metricName values by default (HTTP 422). If your billable unit isn't showing up downstream, Catalog → Billable Units is the first place to check — the most common cause is "the unit was never created in this tenant."

One pipeline once events land

After ingest, every event walks the same path: catalog enrichment → optional filter-condition routing → write to usage_events → optional per-event revenue estimation → indexed for the analytics tier. The protocol doesn't change anything downstream of the receiver — same rate cards, same invoice, same analytics.

Gateways — zero-code metering at the API gateway edge (the most common HTTP-shaped path).
SDKs — language-specific HTTP clients with buffering and retry.
Operations → Alerts & Notifications — outbound webhooks (the opposite direction of Webhook Ingestion).
Intelligence → Ingestion — read-side view of every event that landed, regardless of protocol.