Choosing an integration pattern
There are three ways for your system to learn about new inbound documents and status changes: webhooks, SP2SP messaging, or polling.
Sending documents is always done the same way: your system calls MAPI (see Sending messages).
What differs between integrations is how your system finds out that something has happened, for example that a new invoice has arrived or that an outbound invoice has been delivered or rejected.
Unimaze supports three integration patterns for this:
- Webhooks (recommended): Unimaze calls your HTTPS endpoint when an event occurs.
- SP2SP integration: you act as a service provider and receive documents and message level responses (MLRs / eMLRs) as messages.
- Polling (legacy): your system calls MAPI on a schedule to check for pending messages.
Overview
| Webhooks | SP2SP integration | Polling (legacy) | |
|---|---|---|---|
| Recommended for | ERP and SaaS back-ends integrating with MAPI | Service providers and access points exchanging with Unimaze as a peer | Existing integrations |
| How you are notified | Unimaze sends an HTTP POST to your endpoint | Documents and MLRs/eMLRs are delivered to you as messages | Your system calls GET /messages?status=pendingdelivery periodically |
| Latency | Near real-time | Near real-time | Depends on your polling interval |
| Status updates for outbound messages | Status events (messageStatusChanged, taxReportingStatusChanged, …) | MLR / eMLR messages | Through GET /messages/:mid/status or MLRs |
| Acknowledging inbound messages | mark-as-delivered / mark-as-imported after a notification | Handled by the AS4 / AS2 protocol | mark-as-delivered / mark-as-imported after each poll |
| What you need to host | An HTTPS endpoint reachable from the internet | A Peppol AS4 access point or a dedicated AS2 connection | Nothing |
| Status | Recommended for new integrations | Supported | Maintained, not recommended for new integrations |
Which one should I choose?
flowchart TD
A[New integration?] -->|No, existing polling client| P[Polling: keep it for now, plan a move to webhooks]
A -->|Yes| B{Are you a service provider<br/>or access point?}
B -->|Yes| S[SP2SP integration]
B -->|No, ERP or SaaS back-end| C{Can you expose an<br/>HTTPS endpoint?}
C -->|Yes| W[Webhooks]
C -->|No| P2[Polling]
The patterns can be combined. For example, a service provider can send over AS4 / AS2 while receiving inbound documents through webhook events and MAPI (one-way SP2SP).
Another common setup uses webhooks to trigger an import right away, with an infrequent polling job as a safety net that picks up anything that was missed.
Next steps
Updated 9 days ago