Get Started with Webhooks

Create and register a webhook consumer to start receiving events.

This guide walks you through setting up a webhook consumer that can integrate with Paxos to receive events that occur on the platform. Once completed you should have a webhook consumer, tested locally, and be ready to integrate and test in sandbox; this guide should take less than an hour to complete.

➊ Create a Webhook Consumer

To receive Paxos events, set up your webhook consumer that receives events as an HTTP/HTTPS POST endpoint using your language and tools of choice.

Go

paxos_webhook_consumer.go

http.HandleFunc("/webhook/paxos", func(w http.ResponseWriter, req *http.Request) {
    payload, err := io.ReadAll(req.Body)
    if err != nil {
        fmt.Fprintf(os.Stderr, "error reading request body %v\n", err)
        w.WriteHeader(http.StatusServiceUnavailable)
        return
    }

    event := paxos.Event{}
    if err = json.Unmarshal(payload, &event); err != nil {
        fmt.Fprintf(os.Stderr, "error parsing webhook event: %v\n", err)
        w.WriteHeader(http.StatusBadRequest)
        return
    }

    if event.IsTest {
        fmt.Println("Received test event, ignoring...")
        w.WriteHeader(http.StatusOK)
        return
    }

    // Unmarshal the event data into an appropriate struct depending on its Type
    switch event.Type {
    case "identity.approved":
        fmt.Printf("received documents required event: %v\n, processing...", event)
        // process documents required event
    }

    w.WriteHeader(http.StatusOK)
})

We are currently working on providing client libraries for the Paxos event object. In the meantime, please directly use the definition below:

Go

paxos/event.go

package paxos

type Event struct {
    ID     string    `json:"id"`
    Type   string    `json:"type"`
    Source string    `json:"source"`
    Time   time.Time `json:"time"`
    Object string    `json:"object"`
    IsTest bool      `json:"is_test"`
}

➋ Register the Webhook via Dashboard

Log in to your Dashboard account and navigate to the Webhooks section under the Developer tab. Configure your webhook with:

• Endpoint URL: Your webhook consumer endpoint URL
• Auth Type: Select your authentication method (API Key or OAuth)
• Authentication: Configure your selected authentication method
  • API Key: Provide the API Key Header name and API Key value that Paxos will include when calling your endpoint
  • OAuth: Provide the OAuth endpoint URL, Client ID, and Client Secret
• Event Types: Select which event types you would like to receive and process
• Rate Limit: Set the rate limit (1-100 requests per second, default is 10 RPS)

Paxos does not currently support consumer-side signature-verification on webhook event messages. To keep things secure, Paxos does not include the full event object in the webhook payload and requires you to make an authenticated request to Get Event to fetch the full event object.

Paxos is working on adding signature verification support for webhook messages. This documentation will be updated once this feature is available.

➌ Test the Webhook

Once your webhook is successfully created and shows an Active status in Dashboard, use the Test feature to send test events to your endpoint. For step-by-step instructions, see Test a Webhook. Verify that your consumer receives and processes the events correctly.

Webhook Payload Format

Each webhook event sent to your endpoint contains the following fields:

Parameter	Description	Example
id	The unique identifier of the event. This id can be used to fetch the full details of the event from the Events API.	bd019f1c-89a7-4372-9d21-eaad9280dc41
type	The type of the event. More details about available event types can be found in the Webhooks API Reference.	identity.approved
source	The source of the event. This will always be com.paxos.	com.paxos
time	The time the event was created. Formatted according to RFC3339 date-time.	2025-01-01T14:30:02Z
object	The object type of the event. This will always be event.	event
is_test	Whether the event was a test event. Test events are only sent via the Test feature in Dashboard.	false