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

    // 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
    }
})
We are currently working on providing client libraries for the Paxos event object. In the meantime, please directly use the definition below:
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"`
}

​
➋ Test the Consumer Locally

While we work on a CLI for testing your consumer locally, please directly test with the provided sample event payload below and reach out to Support should you require any further assistance setting up your consumer.
The below curl command contains an example event that Paxos will send you when an identity is approved. We do not send the whole event payload to you in the webhook message, to get the whole payload you will need to integrate with the Events API to call Get Event using the event ID (id) provided in the above payload. 
curl -X POST http://localhost:8080/webhook/paxos \
     -H "Content-Type: application/json" \
     -d '{
           "id": "bd019f1c-89a7-4372-9d21-eaad9280dc41",
           "type": "identity.approved",
           "source": "com.paxos",
           "time": "2025-01-07T14:30:02Z",
           "object": "event"
         }'
When running the above, your consumer should receive the event, printing to standard output the below message: received documents required event: {bd019f1c-89a7-4372-9d21-eaad9280dc41 identity.approved com.paxos 2025-01-07 14:30:02 +0000 UTC event}

​
Webhook Payload Format

ParameterDescriptionExample
idThe 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
typeThe type of the event. More details about available event types can be found on the corresponding events page, such as Identity Events.identity.disabled
sourceThe source of the event. This will always be com.paxos.com.paxos
timeThe time the event was created. Formatted according to RFC3339 date-time.2025-01-01T14:30:02Z
objectThe object type of the event. This will always be event.event

​
➌ Secure the Consumer

You must secure your consumer’s endpoint by authenticating using either:
  • API Key, a secret key we will include in the header when calling your webhook consumer endpoint. You will need to let us know the API Key Header and the API Key.
  • OAuth, we will call your OAuth client using the provided client id / key to receive credentials to call your endpoint. You will need to provide us with the OAuth endpoint URL and the Client ID and the Client Secret.
We do not currently support consumer-side signature-verification on our webhook event messages. To keep things secure, we therefore do not include the full event object in the webhook payload and require you to make an authenticated request to Get Event in order to fetch the full event object.

​
➍ Register the Consumer

We’re working on supporting self-service registration in Dashboard, in the meantime please contact Support to initiate webhook registration. You’ll need to let us know:
  • Which event types you would like to receive and process
  • Your webhook consumer endpoint URL
  • The authentication method of your webhook consumer
  • The environment (Sandbox or Prod) you would like to integrate with