Events & Webhooks

Consume Paxos events through webhooks or the Events API for real-time notifications.

Paxos delivers notifications about resource changes (identity approvals, transfer completions, orchestration status updates) through events. You can consume events in two ways:

• Webhooks — Paxos pushes a notification to your endpoint when something happens
• Events API — You poll the Events API to fetch events on your own schedule

Webhook Payload Pattern

Paxos webhooks use a reduced-payload approach. The webhook notification contains a summary (event ID, type, source, and timestamp) but not the full resource. Your application must call GetEvent to fetch the complete event details.

This pattern ensures that sensitive data is only delivered through authenticated API calls.

Go

// In your webhook HTTP handler
func handleWebhook(w http.ResponseWriter, r *http.Request) {
    body, _ := io.ReadAll(r.Body)

    // ParseEvent extracts the event ID from the webhook body,
    // then fetches the full event via the Events API
    event, err := client.Webhooks.ParseEvent(r.Context(), body)
    if err != nil {
        http.Error(w, "failed to parse event", http.StatusBadRequest)
        return
    }

    switch event.Type {
    case "identity.approved":
        fmt.Printf("Identity %s approved\n", event.ResourceID)
    case "transfer.crypto.deposit.completed":
        fmt.Printf("Crypto deposit %s completed\n", event.ResourceID)
    }

    w.WriteHeader(http.StatusOK)
}

Webhook Endpoint Security

Paxos authenticates with your webhook endpoint using one of two methods. Configure these in the Dashboard:

• API Key — Set a custom header name and value. Paxos includes this header in every webhook request. Validate it in your handler.
• OAuth — Provide your OAuth token endpoint. Paxos obtains a token from your endpoint before calling your webhook.

Paxos does not currently sign webhook payloads. Payload signing is planned for a future release. In the meantime, ParseEvent fetches the canonical event from the API to ensure authenticity.

Polling with the Events API

As an alternative to webhooks, poll the Events API to fetch events:

Go

iter := client.Events.ListEvents(ctx, &paxos.ListEventsRequest{
    Limit: 100,
})

for iter.Next() {
    event := iter.Current()
    fmt.Printf("Event: %s — %s\n", event.ID, event.Type)
}
if err := iter.Err(); err != nil {
    log.Fatal(err)
}

Common Event Types

Event Type	Description
identity.approved	Identity has been approved for transactions
identity.denied	Identity verification was denied
transfer.crypto.deposit.completed	Crypto deposit confirmed on-chain
transfer.crypto.withdrawal.completed	Crypto withdrawal confirmed on-chain
transfer.wire.deposit.completed	Wire deposit has arrived
transfer.wire.withdrawal.completed	Wire withdrawal has been sent
orchestration.completed	Stablecoin orchestration finished successfully
orchestration.failed	Stablecoin orchestration failed

For the full list of event types and webhook payloads, see the Webhooks API Reference.

Handling Events Idempotently

Webhooks may be delivered more than once. Deduplicate by tracking the event.id:

// Example: skip already-processed events
if alreadyProcessed(event.ID) {
    return // skip duplicate
}
process(event)
markAsProcessed(event.ID)

For more details on webhook configuration and retry behavior, see the Webhooks Guide.