Webhook Events Reference
Complete reference of all webhook events sent by GoRoute.
Event Structure​
All webhook events follow this structure:
{
"event": "event.type",
"event_id": "evt_abc123def456",
"timestamp": "2024-01-15T10:30:00.000Z",
"organization_id": "org_xyz789",
"data": {
// Event-specific payload
}
}
Document Events​
document.received​
Triggered when a document is received from the Peppol network.
{
"event": "document.received",
"event_id": "evt_abc123",
"timestamp": "2024-01-15T10:30:00.000Z",
"organization_id": "org_xyz789",
"data": {
"transaction_id": "tx_def456",
"document_id": "doc_ghi789",
"sender": {
"scheme": "0192",
"identifier": "987654321",
"name": "Sender Company AS"
},
"receiver": {
"scheme": "0192",
"identifier": "123456789",
"name": "Your Company AS"
},
"document_type": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2",
"document_type_code": "380",
"invoice_number": "INV-2024-00123",
"issue_date": "2024-01-15",
"currency": "EUR",
"total_amount": 1210.00,
"tax_amount": 210.00,
"received_at": "2024-01-15T10:30:00.000Z",
"download_url": "https://app.goroute.ai/peppol-api/api/v1/documents/doc_ghi789/download",
"attachments": [
{
"filename": "invoice.pdf",
"mime_type": "application/pdf",
"size_bytes": 45678
}
]
}
}
document.validated​
Triggered when document validation completes.
{
"event": "document.validated",
"event_id": "evt_val123",
"timestamp": "2024-01-15T10:30:00.000Z",
"organization_id": "org_xyz789",
"data": {
"document_id": "doc_ghi789",
"valid": true,
"validation_layers": {
"schema": {"passed": true},
"schematron": {"passed": true, "warnings": 0, "errors": 0},
"business_rules": {"passed": true}
},
"warnings": []
}
}
Transaction Events​
transaction.created​
Triggered when a new outbound transaction is created.
{
"event": "transaction.created",
"event_id": "evt_tc123",
"timestamp": "2024-01-15T10:30:00.000Z",
"organization_id": "org_xyz789",
"data": {
"transaction_id": "tx_abc123",
"status": "pending",
"sender": {
"scheme": "0192",
"identifier": "123456789"
},
"receiver": {
"scheme": "0192",
"identifier": "987654321"
},
"document_type": "invoice",
"invoice_number": "INV-2024-00001",
"created_at": "2024-01-15T10:30:00.000Z"
}
}
transaction.accepted​
Triggered when the Peppol network accepts the document.
{
"event": "transaction.accepted",
"event_id": "evt_ta123",
"timestamp": "2024-01-15T10:31:00.000Z",
"organization_id": "org_xyz789",
"data": {
"transaction_id": "tx_abc123",
"status": "accepted",
"accepted_at": "2024-01-15T10:31:00.000Z",
"message_id": "msg_peppol123"
}
}
transaction.delivered​
Triggered when the document is successfully delivered to the recipient.
{
"event": "transaction.delivered",
"event_id": "evt_td123",
"timestamp": "2024-01-15T10:32:00.000Z",
"organization_id": "org_xyz789",
"data": {
"transaction_id": "tx_abc123",
"status": "delivered",
"delivered_at": "2024-01-15T10:32:00.000Z",
"delivery_receipt": {
"received_at": "2024-01-15T10:32:00.000Z",
"receiver_endpoint": "https://receiver-ap.example.com/as4"
}
}
}
transaction.failed​
Triggered when document delivery fails.
{
"event": "transaction.failed",
"event_id": "evt_tf123",
"timestamp": "2024-01-15T10:35:00.000Z",
"organization_id": "org_xyz789",
"data": {
"transaction_id": "tx_abc123",
"status": "failed",
"failed_at": "2024-01-15T10:35:00.000Z",
"error": {
"code": "TX_005",
"message": "Delivery failed after 3 attempts",
"details": "Recipient endpoint returned HTTP 503"
},
"retry_count": 3,
"will_retry": false
}
}
Response Events​
response.received​
Triggered when an Invoice Response (MLR) is received.
{
"event": "response.received",
"event_id": "evt_rr123",
"timestamp": "2024-01-15T11:00:00.000Z",
"organization_id": "org_xyz789",
"data": {
"response_id": "resp_abc123",
"original_transaction_id": "tx_abc123",
"original_invoice_number": "INV-2024-00001",
"status_code": "AP",
"status_reason": "Invoice approved for payment",
"received_at": "2024-01-15T11:00:00.000Z",
"sender": {
"scheme": "0192",
"identifier": "987654321"
}
}
}
Status Codes:
| Code | Meaning |
|---|---|
| AP | Approved |
| RE | Rejected |
| CA | Conditionally Accepted |
| PD | Pending |
| IP | In Process |
Participant Events​
participant.registered​
Triggered when a participant is successfully registered on Peppol.
{
"event": "participant.registered",
"event_id": "evt_pr123",
"timestamp": "2024-01-15T09:00:00.000Z",
"organization_id": "org_xyz789",
"data": {
"participant_id": "part_abc123",
"scheme": "0192",
"identifier": "123456789",
"name": "New Company AS",
"capabilities": [
{
"document_type": "invoice",
"process_id": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0"
},
{
"document_type": "credit_note",
"process_id": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0"
}
],
"registered_at": "2024-01-15T09:00:00.000Z"
}
}
participant.updated​
Triggered when participant capabilities are updated.
{
"event": "participant.updated",
"event_id": "evt_pu123",
"timestamp": "2024-01-15T10:00:00.000Z",
"organization_id": "org_xyz789",
"data": {
"participant_id": "part_abc123",
"scheme": "0192",
"identifier": "123456789",
"changes": {
"capabilities_added": [
{
"document_type": "order",
"process_id": "urn:fdc:peppol.eu:2017:poacc:ordering:01:1.0"
}
],
"capabilities_removed": []
},
"updated_at": "2024-01-15T10:00:00.000Z"
}
}
participant.deregistered​
Triggered when a participant is removed from Peppol.
{
"event": "participant.deregistered",
"event_id": "evt_pd123",
"timestamp": "2024-01-15T17:00:00.000Z",
"organization_id": "org_xyz789",
"data": {
"participant_id": "part_abc123",
"scheme": "0192",
"identifier": "123456789",
"reason": "Customer request",
"deregistered_at": "2024-01-15T17:00:00.000Z"
}
}
Organization Events​
organization.quota.warning​
Triggered when approaching monthly quota limit.
{
"event": "organization.quota.warning",
"event_id": "evt_qw123",
"timestamp": "2024-01-20T00:00:00.000Z",
"organization_id": "org_xyz789",
"data": {
"quota_type": "transactions",
"limit": 10000,
"used": 8500,
"percentage": 85,
"period": "2024-01",
"warning_threshold": 80
}
}
Webhook Headers​
All webhooks include these headers:
| Header | Description |
|---|---|
X-Webhook-Signature | HMAC-SHA256 signature |
X-Webhook-Event | Event type |
X-Webhook-ID | Unique event ID |
X-Webhook-Timestamp | Event timestamp |
Verifying Webhooks​
import hmac
import hashlib
def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
"""Verify webhook signature."""
expected = hmac.new(
secret.encode(),
payload,
hashlib.sha256
).hexdigest()
return hmac.compare_digest(f"sha256={expected}", signature)
# In your webhook handler
@app.post("/webhooks/goroute")
async def handle_webhook(request: Request):
payload = await request.body()
signature = request.headers.get("X-Webhook-Signature")
if not verify_webhook(payload, signature, WEBHOOK_SECRET):
raise HTTPException(status_code=401, detail="Invalid signature")
event = await request.json()
# Process event...
Retry Policy​
If your endpoint returns a non-2xx status code, GoRoute retries:
| Attempt | Delay |
|---|---|
| 1 | Immediate |
| 2 | 5 minutes |
| 3 | 30 minutes |
| 4 | 2 hours |
| 5 | 24 hours |
After 5 failures, the webhook is marked as failed and can be viewed in the dashboard.