Webhooks

AGG sends webhook events to your endpoints when key actions happen in your app — user signups, wallet provisioning, trades, and market resolutions. Webhooks are delivered with cryptographic signatures so you can verify authenticity.

import { parseWebhookEvent } from "@agg-build/sdk/server";

const event = parseWebhookEvent(rawBody, req.headers, process.env.AGG_WEBHOOK_SECRET!);

How it works

Create a webhook endpoint from the admin dashboard. Select a URL and the event types you want to receive. The dashboard displays your signing secret (whsec_...) — store it in your secrets manager immediately.

Receive events

AGG sends POST requests to your URL with a JSON payload and Webhook-Signature header. Events are delivered at least once with automatic retries on failure.

Verify the signature

Use parseWebhookEvent from the SDK to verify the signature and parse the event in one call. This prevents spoofed requests.

Return 2xx

Respond with any 2xx status code within 30 seconds. Non-2xx responses or timeouts trigger automatic retries with exponential backoff.

Event types

Event	Trigger	Payload
`accounts.created`	New user created in your app	`userId`, `appId`, `email`
`accounts.linked`	User linked to an external ID	`userId`, `externalId`
`wallets.ready`	Server wallet provisioned	`userId`, `evmAddress`, `svmAddress`
`trades.placed`	Trade order submitted	`orderId`, `userId`, `side`
`trades.filled`	Trade order filled	`orderId`, `userId`, `status`
`markets.resolved`	Market resolved (summary per app)	`venueMarketId`, `outcome`, `affectedUsersCount`

Webhook payloads are intentionally minimal — they carry IDs and timestamps. Query the API for full details (e.g., order breakdown, fill amounts, market data). accounts.created.email is populated when AGG has an email from magic-link or OAuth sign-in; otherwise it is null.

Delivery guarantees

At-least-once delivery — events may be delivered more than once. Use the id field to deduplicate.
Retry schedule — failed deliveries retry at 5s, 5m, 30m, 2h, 5h, 10h, 10h intervals.
Endpoint disabling — endpoints that fail continuously for 5 days are automatically disabled.
Ordering — events for the same app are delivered in order, but no cross-app ordering is guaranteed.

Signature headers

Every webhook delivery includes these headers:

Header	Description
`Webhook-Id`	Unique message ID (for deduplication)
`Webhook-Timestamp`	Unix timestamp of the delivery attempt
`Webhook-Signature`	HMAC-SHA256 signature for verification

Next steps

Verifying signatures

Verify webhook authenticity with the SDK or manually

Managing endpoints

Rotate secrets and replay deliveries

Event reference

Full payload schemas for every event type