Skip to main content
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-market/sdk/server";

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

​
How it works

1

Register an endpoint

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.
2

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.
3

Verify the signature

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

Return 2xx

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

​
Event types

EventTriggerPayload
accounts.createdNew user created in your appuserId, appId
accounts.linkedUser linked to an external IDuserId, externalId
wallets.readyServer wallet provisioneduserId, evmAddress, svmAddress
trades.placedTrade order submittedorderId, userId, side
trades.filledTrade order filledorderId, userId, status
markets.resolvedMarket 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).

​
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:
HeaderDescription
Webhook-IdUnique message ID (for deduplication)
Webhook-TimestampUnix timestamp of the delivery attempt
Webhook-SignatureHMAC-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