Custom Events

Send product events from your own systems to trigger automations, build segments, and query behavior alongside onchain activity.

Custom events let you send anything that happens in your product — a signup, a deposit, a plan upgrade, a support ticket — into Onchain Suite. Once ingested, an event can trigger an automation, feed a segment, and be queried in SQL next to onchain and messaging data.

Event names are entirely free-form. There is no schema to register and no reserved vocabulary — send first_deposit and it exists.

Sending your first event

Ingestion is authenticated with a secret key, so it happens server-side. The organization is derived from the key.

curl -X POST https://api.onchainsuite.com/api/v1/events \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "first_deposit",
    "contact": { "walletAddress": "0xabc..." },
    "attributes": { "tier": "gold" },
    "payload": { "amountUsd": 2500, "chain": "base-mainnet" },
    "idempotencyKey": "deposit:0xabc:9184",
    "occurredAt": "2026-07-19T12:00:00.000Z"
  }'

Returns 202 Accepted:

{
  "accepted": true,
  "deduplicated": false,
  "idempotencyKey": "deposit:0xabc:9184"
}

Ingestion is asynchronous — 202 means accepted for processing, not that automations have already run.

Request fields

event · string · required

Event name. Must match ^[a-zA-Z0-9_.:-]{1,64}$ and is lowercased on arrival, so First_Deposit and first_deposit are the same event.

contact · object · required

Who the event belongs to. Must contain at least one of email, walletAddress, or externalId.

contact.email · string

Valid email, max 320 characters.

contact.walletAddress · string

Max 128 characters. Lowercased on arrival, so casing never causes a mismatch.

contact.externalId · string

Your own user ID. Max 128 characters, case preserved.

attributes · object

Contact traits merged onto the contact record. Max 50 keys; values must be string, number, or boolean; string values max 1024 bytes.

payload · object

Event-specific data, kept with the event rather than the contact. Max 16 KB serialized. Nested objects allowed.

idempotencyKey · string

Your dedup key, max 256 characters. Strongly recommended — see Idempotency.

occurredAt · string

ISO 8601 timestamp of when the event happened. Defaults to now. Rejected if older than 7 days or more than 5 minutes in the future.

test · boolean

Dry run — see Testing safely.

attributes vs payload

This distinction matters more than it looks:

	attributes	payload
Stored on	The contact, merged and persistent	The event, immutable
Use for	Traits: tier, plan, country	Facts: amountUsd, txHash
Overwrites	Yes — last write wins per key	No
Size	50 keys, 1 KB per value	16 KB total

Put things that describe the person in attributes, and things that describe the event in payload.

Batch ingestion

Send up to 100 events in one request:

curl -X POST https://api.onchainsuite.com/api/v1/events/batch \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      { "event": "account_created", "contact": { "email": "[e-mail]" } },
      { "event": "first_deposit",   "contact": { "walletAddress": "0xabc..." } }
    ]
  }'

Results come back in request order:

{
  "results": [
    { "accepted": true, "deduplicated": false, "idempotencyKey": "…" },
    { "accepted": false, "deduplicated": false, "error": "…" }
  ]
}

A batch always returns 202, even when individual events fail. One bad event never rejects the others — you must inspect each result. Rate-limit rejections also surface as per-item error strings rather than a top-level 429.

Identity resolution

Each event is matched to a contact in strict priority order:

1. Wallet address

   Case-insensitive match on walletAddress.

2. Email

   Matched through a blind index, so encrypted email still resolves.

3. External ID

   Matched against externalId stored in contact metadata.

If no contact matches, one is created. A wallet-only contact is valid — email is not required. Any attributes you send are merged into the new contact’s metadata, and externalId is backfilled onto existing contacts that lack one.

Because the first matching identifier wins, sending both walletAddress and email resolves on the wallet. To merge an email onto an existing wallet contact, send both — the wallet finds the record, and the email is stored on it.

Idempotency

Every event gets an idempotency key, scoped to your organization. A repeat of the same key is accepted but not reprocessed, and returns deduplicated: true.

When you don’t supply one, it’s derived by hashing the event name, all three identifiers, and occurredAt.

Retries are not deduplicated unless you send an explicit idempotencyKey or an explicit occurredAt. The derived key includes occurredAt, which defaults to now — so the same call made twice a second apart produces two different keys and two events, which can fire an automation twice.

Always send an idempotencyKey built from something stable in your system, like deposit:<txHash>:<logIndex>.

Testing safely

Two ways to dry-run:

• Send with a sk_test_* key — everything from that key is a dry run automatically.
• Send "test": true with a live key.

A dry-run event reports how many automations it would have matched, but creates no automation entries, so nothing sends. Test events are also hidden from the event catalog and excluded from the app_events SQL table, so they never contaminate a segment or report.

Triggering automations

Custom events are a first-class automation trigger. Use trigger type app_event (aliases custom_event, app-event, custom-event, appevent are all accepted).

{
  "type": "app_event",
  "eventNames": ["first_deposit"],
  "filters": [
    { "path": "tier", "operator": "eq", "value": "gold" },
    { "path": "amountUsd", "operator": "exists" }
  ]
}

An empty event-name list is a wildcard. A trigger with no event and no eventNames matches every custom event in your organization. Always name the events you want.

Filter paths

Filters read a flat context where your payload keys are spread in at the top level. So the path is amountUsd, not payload.amountUsd:

{ "path": "amountUsd", "operator": "exists" }

Available alongside your payload keys: event, contactId, walletAddress, email, externalId. A payload key with one of those names overrides the built-in value, so avoid naming a payload field email.

Operators are eq, neq, in, contains, and exists — the same set used by on-chain triggers, and all filters must pass. See Triggers and Conditions for the details, including the note that unrecognized operators are silently dropped.

End-to-end: notify a user from an offchain event

This is the most common reason to send custom events — something happens in your product, and you want the user to see an in-app notification in your dApp. Here’s the whole path, and how to wire it up.

There is no direct event-to-push shortcut — an automation is always the bridge. That’s a feature: it means the same event can fan out to in-app, email, tags, and webhooks without your backend knowing about any of them.

1. Add the in-app SDK to your dApp

   Follow the in-app notifications quickstart. Two lines authenticate the wallet and open the socket:

   import { OnchainSuite } from "@onchainsuite/sdk";
   
   const os = new OnchainSuite("pk_live_yourorg_xxx", {
     apiBaseUrl: "https://api.onchainsuite.com",
   });
   await os.start(); // wallet signs in, notifications start showing
   
2. Build an automation: app_event trigger → send_inapp

   Create an automation whose trigger is your event and whose only action sends an in-app push. See Create an Automation.

   {
     "triggerSpec": { "type": "app_event", "event": "first_deposit" },
     "graph": {
       "nodes": [
         { "id": "t1", "type": "app_event",
           "data": { "actionType": "app_event", "event": "first_deposit" } },
         { "id": "n1", "type": "send_inapp",
           "data": {
             "actionType": "send_inapp",
             "recipientMode": "triggering_profile",
             "title": "Deposit received",
             "body": "Your first deposit is in. Welcome aboard."
           } }
       ],
       "edges": [ { "id": "e1", "source": "t1", "target": "n1" } ]
     }
   }
   

   recipientMode: "triggering_profile" sends to the contact the event resolved to — you don’t specify a wallet on the node.

3. Activate AND publish it

   Both are required. An active-but-unpublished automation matches your event and creates an entry, but runs an empty graph and sends nothing. See the publish step.

4. Fire the event from your backend

   curl -X POST https://api.onchainsuite.com/api/v1/events \
     -H "Authorization: Bearer sk_live_…" \
     -H "Content-Type: application/json" \
     -d '{
       "event": "first_deposit",
       "contact": { "walletAddress": "0xabc..." },
       "payload": { "amountUsd": 250 }
     }'
   

   If a socket is connected for that wallet, the push arrives in about a second. If not, it’s stored and replayed the next time the wallet connects.

The wallet is the key

The in-app SDK authenticates by wallet, so the push can only reach a wallet. This is the one requirement that catches people out:

The event must resolve to a contact with a wallet address — either send contact.walletAddress directly, or send an email/externalId that matches a contact who already has a wallet on file.

If the resolved contact has no wallet, the send_inapp step fails for that entry (and eventually dead-letters) rather than delivering. An email-only signup, for example, can’t receive an in-app push until that contact is linked to a wallet.

The wallet is taken from the event’s contact.walletAddress if present, otherwise from the matched contact record. To also reach walletless contacts, branch the automation to a send_email step — see Connect to Campaigns.

Offchain vs onchain triggers

Both drive the same actions, including send_inapp. The difference is where the event comes from:

	app_event (offchain)	onchain_event
Source	Your backend, via POST /events	Chain activity, observed for you
You supply	Event name, identifiers, payload	Nothing — the chain does
Use it for	Signups, deposits, product state	Mints, swaps, approvals, liquidations

Reach for app_event when the thing that happened lives in your systems. Reach for onchain_event when it’s something the chain already knows — see Contract-Based Flows.

Querying events in SQL

Events land in the app_events table in the Intelligence SQL editor:

-- Contacts who created an account but never deposited
SELECT c.email, c.wallet_address, created.occurred_at
FROM app_events created
JOIN contacts c ON c.id = created.contact_id
LEFT JOIN app_events deposited
  ON deposited.contact_id = created.contact_id
  AND deposited.event = 'first_deposit'
WHERE created.event = 'account_created'
  AND deposited.id IS NULL
ORDER BY created.occurred_at DESC
LIMIT 100

Use occurred_at for time windows — it’s when the event happened in your system. created_at is when we received it.

Discovering event names

GET /api/v1/events/catalog returns the distinct event names seen in the last 30 days with counts, ordered by frequency. This powers autocomplete in the builder and is useful for spotting typos in event names.

{
  "events": [{ "event": "first_deposit", "count": 42 }],
  "windowDays": 30
}

Test events are excluded, and the list is capped at 200 names.

Limits and errors

Limit	Value
Ingest rate	50 events/sec per organization, burst 100
Batch size	100 events
Event name	64 characters
Attributes	50 keys, 1 KB per value
Payload	16 KB
Event age	7 days back, 5 minutes forward

Ingestion itself is free and not metered against your plan — only messages sent as a result are.

Status	Meaning
202	Accepted (check deduplicated)
400	Validation failure — the message names the field
401	Missing, invalid, or revoked secret key
429	RATE_LIMITED — back off and retry
503	INGEST_UNAVAILABLE — retry with the same idempotencyKey

429 responses do not currently include a Retry-After header. Use exponential backoff, and keep the same idempotencyKey across retries so a late success doesn’t double-fire.

Things to know

Events are retained indefinitely

There is currently no automatic pruning of custom events. Plan for the table to grow, and prefer payload fields you’ll actually query.

The rate limit is per instance

The 50/sec bucket is held in memory per API instance, so effective throughput scales with the number of running instances. Treat 50/sec as the safe floor rather than a hard ceiling.

Unknown top-level fields are dropped silently

Fields outside the documented set are stripped rather than rejected. If data seems to be missing, check that it’s nested inside attributes or payload rather than sitting at the top level.

Put the trigger node first in the builder

Custom-event trigger nodes aren’t yet recognized by the builder’s trigger-node detection, which falls back to the first node in the graph. Keep your app_event trigger as the first node so run inspection labels steps correctly.