> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onchainsuite.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 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.
```bash theme={"dark"}
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`:
```json theme={"dark"}
{
"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 name. Must match `^[a-zA-Z0-9_.:-]{1,64}$` and is lowercased on arrival, so `First_Deposit` and `first_deposit` are the same event.
Who the event belongs to. Must contain at least one of `email`, `walletAddress`, or `externalId`.
Valid email, max 320 characters.
Max 128 characters. Lowercased on arrival, so casing never causes a mismatch.
Your own user ID. Max 128 characters, case preserved.
Contact traits merged onto the contact record. Max 50 keys; values must be string, number, or boolean; string values max 1024 bytes.
Event-specific data, kept with the event rather than the contact. Max 16 KB serialized. Nested objects allowed.
Your dedup key, max 256 characters. Strongly recommended — see [Idempotency](#idempotency).
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.
Dry run — see [Testing safely](#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:
```bash theme={"dark"}
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": "a@example.com" } },
{ "event": "first_deposit", "contact": { "walletAddress": "0xabc..." } }
]
}'
```
Results come back in request order:
```json theme={"dark"}
{
"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:
Case-insensitive match on `walletAddress`.
Matched through a blind index, so encrypted email still resolves.
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::`.
## 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).
```json theme={"dark"}
{
"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`:
```json theme={"dark"}
{ "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](/automation/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.
```mermaid theme={"dark"}
flowchart LR
A[Your backend
POST /events] --> B[app_events]
B --> C[Automation
app_event trigger]
C --> D[send_inapp node]
D --> E[In-app push]
E --> F[SDK in your dApp
PUSH event]
```
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.
Follow the [in-app notifications quickstart](/integrations/in-app-notifications#quickstart-with-the-sdk). Two lines authenticate the wallet and open the socket:
```ts theme={"dark"}
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
```
Create an automation whose trigger is your event and whose only action sends an in-app push. See [Create an Automation](/automation/create-an-automation).
```json theme={"dark"}
{
"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.
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](/automation/create-an-automation).
```bash theme={"dark"}
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](/automation/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](/automation/contract-based-flows).
## Querying events in SQL
Events land in the `app_events` table in the [Intelligence SQL editor](/intelligence/sql-query-editor):
```sql theme={"dark"}
-- 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.
```json theme={"dark"}
{
"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
There is currently no automatic pruning of custom events. Plan for the table to grow, and prefer `payload` fields you'll actually query.
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.
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.
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.