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.

​
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

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:

​
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