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

Java

WebhookServlet.java

public class WebhookServlet extends HttpServlet {

    private final ObjectMapper objectMapper = new ObjectMapper();

    @Override
    protected void doPost(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {
        try {
            PaxosEvent event = objectMapper.readValue(req.getInputStream(), PaxosEvent.class);

            if (event.isTest()) {
                System.out.println("Received test event, ignoring...");
                resp.setStatus(HttpServletResponse.SC_OK);
                return;
            }

            // Unmarshal the event data into an appropriate struct depending on its Type
            switch (event.type()) {
                case "identity.documents_required":
                    System.out.printf("received documents required event: %s, processing...%n", event);
                    // process documents required event
                    break;
                default:
                    System.out.printf("received unknown event type: %s%n", event.type());
                    break;
            }

            resp.setStatus(HttpServletResponse.SC_OK);
        } catch (IOException e) {
            System.err.printf("error reading request body: %s%n", e.getMessage());
            resp.setStatus(HttpServletResponse.SC_SERVICE_UNAVAILABLE);
        } catch (Exception e) {
            System.err.printf("error parsing webhook event: %s%n", e.getMessage());
            resp.setStatus(HttpServletResponse.SC_BAD_REQUEST);
        }
    }
}

Python

paxos_webhook_consumer.py

# using django
@csrf_exempt
def paxos_webhook(request):
    if request.method != 'POST':
        return HttpResponse(status=405)

    try:
        payload = json.loads(request.body)

        if payload.get('is_test'):
            print("Received test event, ignoring...")
            return HttpResponse(status=200)

        event_type = payload.get('type')

        # Unmarshal the event data into an appropriate struct depending on its Type
        if event_type == 'identity.documents_required':
            print(f"received documents required event: {payload}, processing...")
            # process documents required event
        else:
            print(f"received unknown event type: {event_type}")

        return HttpResponse(status=200)
    except json.JSONDecodeError as e:
        print(f"error parsing webhook event: {e}")
        return HttpResponse(status=400)
    except Exception as e:
        print(f"error reading request body: {e}")
        return HttpResponse(status=503)

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"`
}

Java

com/paxos/PaxosEvent.java

package com.paxos;

import java.time.LocalDateTime;

public record PaxosEvent(
    String id,
    String type,
    String source,
    LocalDateTime time,
    String object
    Boolean isTest
) {}

➋ 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_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