> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paxos.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 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 title="paxos_webhook_consumer.go" theme={null}
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 title="WebhookServlet.java" theme={null}
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 title="paxos_webhook_consumer.py" theme={null}
# 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 title="paxos/event.go" theme={null}
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 title="com/paxos/PaxosEvent.java" theme={null}
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](https://dashboard.paxos.com/login) 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](/api-reference/events) 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](/api-reference/endpoints/events/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](/guides/dashboard/webhooks#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](/api-reference/events). | `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](/api-reference/webhooks). | `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` |