Webhooks

Maventa supports registering webhooks that allow your system to receive real-time notifications about important events. Instead of polling the API for updates, you simply create a webhook subscription using the AX API. Whenever one of the subscribed events occurs, for example, when a new invoice arrives or its status changes, Maventa sends an HTTP POST request to the endpoint you have defined. These incoming POST requests are what we refer to as receiving events. This makes your integration more efficient, faster, and easier to scale.

Registering to receive events via webhooks

You can register wbhook subscriptions POST /v1/company/notifications.

For a single company

If you authenticate as an individual company, you can register a webhook that receives events only for that company.

Example registering for DELIVERED, DELIVERY_CONFIRMED and FAILED events for invoices

{
  "destination_type": "WEBHOOK",
  "destination": "https://your.example/endpoint",
  "events": [
    "DOCUMENTS.INVOICE.DELIVERED",
    "DOCUMENTS.INVOICE.DELIVERY_CONFIRMED",
    "DOCUMENTS.INVOICE.FAILED"
  ]
}

{
  "id": "d726d240-4631-483e-a4e3-61bbefa0e7b7",
  "destination_type": "WEBHOOK",
  "destination": "https://your.example/endpoint",
  "events": [
    "DOCUMENTS.INVOICE.DELIVERED",
    "DOCUMENTS.INVOICE.DELIVERY_CONFIRMED",
    "DOCUMENTS.INVOICE.FAILED"
  ]
}

Example registering for all networks and all event types

{
  "destination_type": "WEBHOOK",
  "destination": "https://your.example/endpoint",
  "events": [
   "NETWORKS.*"
  ]
}

{
  "id": "d726d240-4631-483e-a4e3-61bbefa0e7b7",
  "destination_type": "WEBHOOK",
  "destination": "https://your.example/endpoint",
  "events": [
   "NETWORKS.*"
}

For all partner’s companies (Vendor webhooks)

Partners can register webhooks that automatically apply to all companies linked to the partner’s vendor API key. This is a one-time setup, once the subscription is active, your webhook endpoint will receive events for every company associated with that vendor key

To register vendor webhooks, authenticate with the partner company’s credentials and set destination_type to VENDOR_WEBHOOK.

Example registering for all events for all document types

{
  "destination_type": "VENDOR_WEBHOOK",
  "destination": "https://your.example/endpoint",
  "events": [
    "DOCUMENTS.*.*"
  ]
}

{
  "id": "d726d240-4631-483e-a4e3-61bbefa0e7b7",
  "destination_type": "VENDOR_WEBHOOK",
  "destination": "https://your.example/endpoint",
  "events": [
    "DOCUMENTS.*.*"
  ]
}

Vendor key specific webhooks

If you manage multiple vendor API keys and want events separated per key, include vendor_key in the subscription payload to filter which events you receive.

Example registering for DELIVERED, DELIVERY_CONFIRMED and FAILED events for invoices with vendor webhooks:

{
  "destination_type": "VENDOR_WEBHOOK",
  "destination": "https://your.example/endpoint",
  "vendor_key": "your_vendor_api_key_here",
  "events": [
    "DOCUMENTS.INVOICE.DELIVERED",
    "DOCUMENTS.INVOICE.DELIVERY_CONFIRMED",
    "DOCUMENTS.INVOICE.FAILED"
  ]
}

{
  "id": "d726d240-4631-483e-a4e3-61bbefa0e7b7",
  "destination_type": "VENDOR_WEBHOOK",
  "destination": "https://your.example/endpoint",
  "events": [
    "DOCUMENTS.INVOICE.DELIVERED",
    "DOCUMENTS.INVOICE.DELIVERY_CONFIRMED",
    "DOCUMENTS.INVOICE.FAILED"
  ]
}

Handling webhook events

Webhook events are delivered as HTTP POST requests to the endpoint URL (destination) configured during registration. Your webhook endpoint should remain lightweight and respond quickly, handling only minimal processing.

For example, when receiving a DOCUMENTS.INVOICE.RECEIVED event, you should store the event_data and trigger a background process to download the invoice instead of performing heavy or long-running logic in the webhook handler. Webhook requests are expected to complete within 5 seconds. Requests that time out are treated as failures and will be retried.

Maventa webhooks use an at-least-once delivery model. This means the same event may be delivered multiple times, and your system must handle deduplication to prevent duplicate processing of invoice events. A webhook delivery is considered successful only if the endpoint responds with an HTTP 200, 201, or 204 status code. Any other response or a timeout is treated as a failure and will trigger a retry. Retries are performed once per hour, up to a maximum of 24 attempts.

Because webhooks are not guaranteed to be 100% reliable, you should implement safeguards to ensure no events are missed. This can be done by subscribing to unacknowledged webhook events or by using the REST API as a fallback to poll for missing data.

If all webhook deliveries for a subscription continue to fail for one month, the webhook subscription will be automatically disabled.

POST url
Content-type: application/json

{
  "event":           "DOCUMENTS.INVOICE.RECEIVED" | "DOCUMENTS.INVOICE.DELIVERED" | "DOCUMENTS.INVOICE.DELIVERY_CONFIRMED" | "DOCUMENTS.INVOICE.FAILED",
  "company_id":      "string",
  "event_timestamp": "string",
  "event_data":      DocumentsInvoiceReceived | DocumentsInvoiceDelivered | DocumentsInvoiceDeliveryConfirmed | DocumentsInvoiceFailed
}

The event is the name of the event e.g. DOCUMENTS.INVOICE.RECEIVED.

The event_timestamp is the ISO8601 formatted time when the event was originally created.

The company_id is UUID of the company the event has been subscribed by.

The event_data is optional and its structure depends on the name of the event.

type DocumentsInvoiceReceived
{
  "invoice_id":     "string",
  "invoice_number": "string",
  "origin":         "string", // e.g. "PEPPOL"
  "sender_name":    "string",
  "sender_bid":     "string"
}

type DocumentsInvoiceDelivered
{
  "invoice_id":     "string",
  "invoice_number": "string",
  "destination":    "string", // e.g. "PEPPOL"
  "recipient_name": "string",
  "recipient_bid":  "string"
}

type DocumentsInvoiceDeliveryConfirmed
{
  "invoice_id":     "string",
  "invoice_number": "string",
  "destination":    "string", // e.g. "PEPPOL"
  "recipient_name": "string",
  "recipient_bid":  "string"
}

type DocumentsInvoiceFailed
{
  "invoice_id":     "string",
  "invoice_number": "string",
  "destination":    "string", // e.g. "PEPPOL"
  "recipient_name": "string",
  "recipient_bid":  "string",
  "error_message":  "string"
}

Subscribe to unacknowledged webhooks

To improve reliability and ensure that no webhook events are missed, we strongly recommend subscribing to UNACKNOWLEDGED_WEBHOOKS. This subscription notifies you when webhook deliveries have repeatedly fail and provides a controlled mechanism for recovering those events.

When an unacknowledged webhook notification is received, your system can fetch all failed webhook events in a single call using the API method POST /v1/company/notifications_resend_unacknowledged. This endpoint resends all unacknowledged webhook events for the company. Once an event has been successfully processed, any further retry attempts for that event will stop. If all webhook deliveries for a subscription continue to fail for one month, the webhook subscriptions for the company will be automatically disabled.

To enable this functionality, register to the UNACKNOWLEDGED_WEBHOOKS event using the POST /v1/company/notifications.

Example payload:

{
  "destination":      "https://example.com/webhooks/unacknowledged_webhooks?token=1234",
  "destination_type": "WEBHOOK",
  "events":           [ "UNACKNOWLEDGED_WEBHOOKS" ]
}

The notification itself is delivered as the following payload:

{
    "event":           "UNACKNOWLEDGED_WEBHOOKS",
    "company_id":      "string",
    "event_timestamp": "string"
}

Subscribing to unacknowledged webhooks provides proactive visibility into delivery issues. If your system fails to acknowledge webhook events for 24 hours, you will receive a single notification summarizing all unacknowledged events. These notifications are sent once per company per day and can continue for up to one month, helping ensure that delivery failures do not go unnoticed.

Security

To ensure that messages sent to your webhook endpoint originate from Maventa, we recommend adding an authorization mechanism to the webhook URL.

You can use one of the following approaches:

• HTTP Basic Authentication

Example: https://user:examplesecret@your-erp.com/webhooks

When a webhook URL is registered in this format, Maventa will call https://your-erp.com/webhooks and include the HTTP header Authorization: Basic dGVzdDpzZWNyZXQ=

• Secret as a URL parameter

Example: https://your-erp.com/webhooks?secret=examplesecret

Please note that the webhook endpoint must support TLS 1.2. Older protocols, including SSLv2, SSLv3, TLS 1.0, and TLS 1.1, are not supported.

Event types

Maventa supports the following events:

DOCUMENTS.*.DELIVERED

Triggered when a document has been successfully handed over to the selected delivery channel (e.g., Peppol, email, print). DELIVERED indicates that Maventa has completed its part of the transmission, but it does not guarantee that the final recipient received or accepted the document. For example, an email invoice may still fail later if the message bounces due to an invalid address or a full inbox.

You can show this status to your customers, but note that DELIVERED does not always represent final delivery success.

DOCUMENTS.*.DELIVERY_CONFIRMED

The DELIVERY_CONFIRMED status indicates that the delivery channel has successfully acknowledged receipt or completed the delivery. Note that not all delivery routes provide this confirmation. When an invoice receives DELIVERY_CONFIRMED, it is considered fully delivered, and the status will no longer change to FAILED.

DOCUMENTS.*.FAILED

Triggered when a document fails to be delivered due to a final error. This may occur even after a DELIVERED event. The event does include the error details.

DOCUMENTS.*.RECEIVED

Triggered when your company receives an invoice or any document.

NETWORKS.*

Triggered for changes in network registrations, such as for Finnish bank network registration (BANK), opening a scan account (SCAN) or registering your company to receive from Peppol network (PEPPOL). Each event reflects a specific lifecycle action: CREATED, ENABLED, or DISABLED.

For example, when the Finnish bank network connection is successfully opened (might take few days from opening), an event NETWORKS.BANK.ENABLED is triggered.

COMPANIES.AUTHORIZATION.*

When a company’s authorization status changes to either VERIFIED, UNVERIFIED or UNKNOWN.

UNACKNOWLEDGED_WEBHOOKS

Happens when your system experiences issues and fails to respond within 24 hours, the company will receive a single notification encompassing all unacknowledged webhook events. Unacknowledged webhooks are dispatched once per company per day and will continue for up to one month

Webhook examples

Example registering for DELIVERED, DELIVERY_CONFIRMED and FAILED events for invoices

{
  "destination_type": "WEBHOOK",
  "destination": "https://your.example/endpoint",
  "events": [
    "DOCUMENTS.INVOICE.DELIVERED",
    "DOCUMENTS.INVOICE.DELIVERY_CONFIRMED",
    "DOCUMENTS.INVOICE.FAILED"
  ]
}

{
  "id": "d726d240-4631-483e-a4e3-xxxxxxx",
  "destination_type": "WEBHOOK",
  "destination": "https://your.example/endpoint",
  "events": [
    "DOCUMENTS.INVOICE.DELIVERED",
    "DOCUMENTS.INVOICE.DELIVERY_CONFIRMED",
    "DOCUMENTS.INVOICE.FAILED"
  ]
}

Example registering for DELIVERED, DELIVERY_CONFIRMED and FAILED events for invoices with vendor webhooks

{
  "destination_type": "VENDOR_WEBHOOK",
  "destination": "https://your.example/endpoint",
  "vendor_key": "your_vendor_api_key_here",
  "events": [
    "DOCUMENTS.INVOICE.DELIVERED",
    "DOCUMENTS.INVOICE.DELIVERY_CONFIRMED",
    "DOCUMENTS.INVOICE.FAILED"
  ]
}

{
  "id": "d726d240-4631-483e-a4e3-xxxxxxxxx",
  "destination_type": "VENDOR_WEBHOOK",
  "destination": "https://your.example/endpoint",
  "events": [
    "DOCUMENTS.INVOICE.DELIVERED",
    "DOCUMENTS.INVOICE.DELIVERY_CONFIRMED",
    "DOCUMENTS.INVOICE.FAILED"
  ]
}

Example of a payload when invoice is delivered

{
  "event":"DOCUMENTS.INVOICE.DELIVERED",
  "company_id":"53a4e05d-42f0-4e76-acd6-xxxxxxx",
  "event_timestamp":"2019-11-23T12:03:48+02:00",
  "event_data": {
    "invoice_id":"12f88354-5998-495b-8675-xxxxxxxx",
    "invoice_number":"1003",
    "destination":"PEPPOL",
    "recipient_name":"Recipient",
    "recipient_bid":"933646920"
  }
}

Example of a payload when invoice sending fails

{
  "event":"DOCUMENTS.INVOICE.FAILED",
  "company_id":"53a4e05d-42f0-4e76-acd6-xxxxxxxxx",
  "event_timestamp":"2019-11-23T12:03:48+02:00",
  "event_data": {
    "invoice_id":"da01a81d-1995-440c-971b-xxxxxxxxx",
    "invoice_number":"1001",
    "destination":"PEPPOL",
    "recipient_name":"Recipient",
    "recipient_bid":"933646920",
    "error_message": "Error that happened"
  }
}

Example registering for RECEIVED events for invoices

{
  "destination_type": "WEBHOOK",
  "destination": "https://your.example/endpoint",
  "events": [
    "DOCUMENTS.INVOICE.RECEIVED"
  ]
}

{
  "id": "d726d240-4631-483e-a4e3-61bbefa0e7b7",
  "destination_type": "WEBHOOK",
  "destination": "https://your.example/endpoint",
  "events": [
    "DOCUMENTS.INVOICE.RECEIVED"
  ]
}

Example of a payload when invoice is received for a company account

{
  "event":            "DOCUMENTS.INVOICE.RECEIVED",
  "company_id":       "53a4e05d-42f0-4e76-acd6-xxxxxxxxx",
  "event_timestamp":  "2024-11-23T12:03:48+02:00",
  "event_data": {
    "invoice_id":     "c154feee-399b-488e-aecd-xxxxxxxxx",
    "invoice_number": "1002",
    "origin":         "PEPPOL",
    "sender_name":    "Sender",
    "sender_bid":     "937729111"
  }
}

Example registering for RECEIVED events for invoices with vendor webhooks

{
  "destination_type": "VENDOR_WEBHOOK",
  "destination": "https://your.example/endpoint",
  "vendor_key": "your_vendor_api_key_here",
  "events": [
    "DOCUMENTS.INVOICE.RECEIVED"
  ]
}

{
  "id": "d726d240-4631-483e-a4e3-61bbefa0e7b7",
  "destination_type": "VENDOR_WEBHOOK",
  "destination": "https://your.example/endpoint",
  "events": [
    "DOCUMENTS.INVOICE.RECEIVED"
  ]
}