Webhook events
# Introduction
Collect can notify your system of events in real time by means of webhooks: whenever a relevant event occurs on the Collect platform, Collect sends an HTTP POST request with a JSON payload to an endpoint that you provide. Webhooks are the recommended way to keep your administration synchronised with Collect, as they are faster and far more efficient than polling the API for status updates.
Webhooks belong to API v3 and are delivered as JSON.
# How it works
## One endpoint for all events
You provide a single HTTPS endpoint to Collect. All event types are delivered to this one endpoint; there is no separate endpoint per event type. Every payload contains an event_type field, which allows your system to recognise the type of event and process it accordingly.
You decide which event types are sent to your endpoint. Indicate to a POM employee which event types you want to receive; the selection is then configured for your account.
## Delivery
Webhooks are sent as HTTP POST requests with a JSON body (UTF-8 encoded, Content-Type: application/json). Your endpoint must be reachable over HTTPS (port 443).
Return an HTTP 2xx status code to acknowledge receipt. Any other response — or no response — is treated as a failed delivery attempt.
# Security
## Transport
All webhook traffic is sent over HTTPS, so both the payload and the authentication details are encrypted in transit.
## Authentication
Webhook requests are authenticated with OAuth 2. You provide a token endpoint and client credentials; Collect obtains an access token from your token endpoint and includes it as a Bearer token in the Authorization header of each webhook request.
Basic authentication — a fixed username and password in the Authorization header of every request — is also possible, but is strongly discouraged in favour of OAuth 2.
## IP whitelisting
As an additional measure, IP whitelisting can be enabled: webhooks are sent from fixed Collect IP addresses, allowing you to restrict your endpoint to accept requests from these addresses only. IP whitelisting can be set up in coordination with a POM employee.
# Retries and monitoring
If delivery of a webhook fails, Collect automatically retries: up to 5 attempts in total, with 30-minute intervals between attempts. If delivery still fails after the fifth attempt, the webhook is marked as permanently failed in the Collect system.
Failed webhooks that fall outside this retry window can still be re-triggered manually by a POM employee. Contact support if you have missed webhooks — for example after an outage on your side — and want them redelivered.
All webhooks and their delivery status can be monitored on the customer card in the Collect portal. Collect employees additionally have a back-office overview of webhook deliveries, and Collect's development team monitors overall error rates, so excessive failures are noticed on Collect's side as well.
Please note that the availability and health of your endpoint itself remain your responsibility; Collect does not monitor client-side endpoints.
# Payload structure
Every webhook payload is a single flat JSON object; there is no wrapper or envelope element. The following fields are present in nearly every event:
| Field | Type | Description |
|---|---|---|
| id_client | number | Your client ID in Collect. |
| debtornumber | string | Your identifier for the debtor. |
| cid | number or null | Collection order ID. null for events that are not linked to a collection order. |
| mpid | number or null | Message ID of the related message. |
| payment_reference | string | Your identifier for the payment request. |
| id_request_client | string or null | Your own request identifier, echoed back if supplied. |
| event_type | string | The type of event; see the overview below. |
| event_date | string | Date of the event (YYYY-MM-DD), where applicable. |
| event_time | string | Time of the event (HH:MM, 24-hour clock), where applicable. |
Additional fields depend on the event type; see the example payloads.
## Data conventions
| Convention | Description |
|---|---|
| Field names | snake_case: payment_reference, event_type. |
| Identifiers | Numeric Collect identifiers (id_client, cid, mpid, template IDs) are JSON numbers. Identifiers supplied by you (debtornumber, payment_reference, id_request_client) are strings. |
| Amounts | Integers, in cents: 45500 means € 455,00. |
| Dates and times | Strings in the format YYYY-MM-DD and HH:MM. |
| Booleans | JSON true / false. |
| Empty values | Delivered as null. |
| Encoding | UTF-8. |
# Event types
| Event | event_type |
|---|---|
| Payment received | payment |
| Email sent | email |
| SMS sent | sms |
| Letter sent | letter |
| Email bounced | bounce_email |
| Letter undeliverable | bounce_letter |
| SMS undeliverable | bounce_sms |
| Settlement plan started | settlement |
| Settlement instalment failed | settlement_fail |
| Settlement plan completed | settlement_success |
| Payment promise created | payment_promise |
| Payment promise kept | payment_promise_success |
| Payment promise broken | payment_promise_fail |
| Payment promise cancelled | payment_promise_cancel |
| Flow ended without payment | end |
| Case sent to collection agency | collection_agency |
| Data enrichment | data_enrichment |
| General correspondence: sequence bounce | general_correspondence_sequence_bounce |
| Collection fee added | on request¹ |
| Case sent to field collector | on request¹ |
| Case sent to external call centre | on request¹ |
| Case sent to IVR | on request¹ |
| Case cancelled | on request¹ |
| Case withdrawn | on request¹ |
| Proposal sent (Mail to Agree) | on request¹ |
| Proposal expired (Mail to Agree) | on request¹ |
| Proposal accepted (Mail to Agree) | on request¹ |
¹ The event_type values and example payloads for these events are available on request via [email protected].
# Example payloads
## Payment
Sent when a payment is received on a collection order or message.
json
{
"id_client": 1000,
"debtornumber": "123456",
"cid": 2345678910,
"mpid": 1234567890,
"payment_reference": "123456789",
"id_request_client": "test",
"event_type": "payment",
"amount_total": 45500,
"id_bank": "ABNANL2A",
"iban": "GB33BUKB20201555555555",
"bic": "INGBNL2A",
"account_owner": "John Doe",
"event_date": "2024-01-05",
"event_time": "11:27"
}
## Email sent
json
{
"id_client": 1000,
"debtornumber": "123456",
"cid": 2345678910,
"mpid": 1234567890,
"payment_reference": "123456789",
"id_request_client": "test",
"event_type": "email",
"email_address": "[email protected]",
"event_date": "2024-01-01",
"event_time": "19:08",
"template_descr": "Collect Betalingsverzoek"
}
## Letter sent
json
{
"id_client": 1000,
"debtornumber": "123456",
"cid": 2345678910,
"mpid": 1234567890,
"payment_reference": "123456789",
"id_request_client": "test",
"event_type": "letter",
"address_street": "van Coulsterweg",
"address_number": "2",
"address_postcode": "2959CB",
"address_city": "Alblasserdam",
"event_date": "2024-01-01",
"event_time": "15:00",
"template_descr": "Collect Betalingsverzoek"
}
## SMS sent
json
{
"id_client": 1000,
"debtornumber": "123456",
"cid": 2345678910,
"mpid": 1234567890,
"payment_reference": "123456789",
"id_request_client": "test",
"event_type": "sms",
"mobile_number": "+31612345678",
"event_date": "2024-01-01",
"event_time": "15:00",
"template_descr": "Collect Betalingsverzoek"
}
## Email bounced
json
{
"id_client": 1000,
"debtornumber": "12345678",
"cid": null,
"mpid": 1411164477,
"payment_reference": "12345678",
"id_request_client": null,
"event_type": "bounce_email",
"email_address": "[email protected]",
"event_date": "2024-01-01",
"event_time": "01:00"
}
## Letter undeliverable
json
{
"id_client": 1000,
"debtornumber": "12345678",
"cid": null,
"mpid": 1411164477,
"payment_reference": "12345678",
"id_request_client": null,
"event_type": "bounce_letter",
"address_street": "Van Coulsterweg",
"address_number": "2",
"address_postcode": "2316AJ",
"address_city": "Alblasserdam",
"event_date": "2024-01-01",
"event_time": "01:00"
}
## SMS undeliverable
json
{
"id_client": 1000,
"debtornumber": "12345678",
"cid": null,
"mpid": 1411164477,
"payment_reference": "12345678",
"id_request_client": null,
"event_type": "bounce_sms",
"mobile_number": "+31612345678",
"event_date": "2024-01-01",
"event_time": "01:00"
}
## Settlement plan started
json
{
"id_client": 1000,
"debtornumber": "123456",
"cid": 2345678910,
"mpid": 1234567890,
"payment_reference": "1312312",
"id_request_client": "test",
"event_type": "settlement",
"term": 1,
"term_max": 4,
"amount": 12500,
"amount_total": 50000
}
## Settlement instalment failed
json
{
"id_client": 1000,
"debtornumber": "123456",
"cid": 2345678910,
"mpid": 1234567890,
"payment_reference": "1312312",
"id_request_client": "test",
"event_type": "settlement_fail",
"term": 1,
"term_max": 4,
"amount": 12500,
"amount_total": 50000
}
## Settlement plan completed
json
{
"id_client": 1000,
"debtornumber": "123456",
"cid": 2345678910,
"mpid": 1234567890,
"payment_reference": "1312312",
"id_request_client": "test",
"event_type": "settlement_success",
"term": 1,
"term_max": 4,
"amount": 12500,
"amount_total": 50000
}
## Payment promise created
Sent when the debtor or an agent makes a promise to pay the outstanding amount of a collection order by the due date. While the promise is active, the regular flow of the collection order is paused.
json
{
"id_client": 1000,
"debtornumber": "123456",
"cid": 2345678910,
"mpid": null,
"payment_reference": "1312312",
"id_request_client": "test",
"event_type": "payment_promise",
"payment_promise_id": 456,
"status": "active",
"amount": 25000,
"amount_paid": 0,
"due_date": "2026-10-15",
"initiator": "self_service",
"event_date": "2026-10-01",
"event_time": "11:27"
}
## Payment promise kept
Sent when the promised amount has been paid in full.
json
{
"id_client": 1000,
"debtornumber": "123456",
"cid": 2345678910,
"mpid": null,
"payment_reference": "1312312",
"id_request_client": "test",
"event_type": "payment_promise_success",
"payment_promise_id": 456,
"status": "fulfilled",
"amount": 25000,
"amount_paid": 25000,
"due_date": "2026-10-15",
"initiator": "self_service",
"event_date": "2026-10-12",
"event_time": "11:27"
}
## Payment promise broken
Sent when the promised amount has not been paid in full after the due date and the respite days of the promise. amount_paid shows what was paid before the promise was broken.
json
{
"id_client": 1000,
"debtornumber": "123456",
"cid": 2345678910,
"mpid": null,
"payment_reference": "1312312",
"id_request_client": "test",
"event_type": "payment_promise_fail",
"payment_promise_id": 456,
"status": "broken",
"amount": 25000,
"amount_paid": 10000,
"due_date": "2026-10-15",
"initiator": "self_service",
"event_date": "2026-10-18",
"event_time": "11:27"
}
## Payment promise cancelled
Sent when an active promise is cancelled before it is kept or broken, for example because the collection order is withdrawn or paused.
json
{
"id_client": 1000,
"debtornumber": "123456",
"cid": 2345678910,
"mpid": null,
"payment_reference": "1312312",
"id_request_client": "test",
"event_type": "payment_promise_cancel",
"payment_promise_id": 456,
"status": "cancelled",
"amount": 25000,
"amount_paid": 0,
"due_date": "2026-10-15",
"initiator": "self_service",
"event_date": "2026-10-05",
"event_time": "11:27"
}
## Flow ended without payment
json
{
"id_client": 1000,
"debtornumber": "123456",
"cid": 2345678910,
"mpid": 1234567890,
"payment_reference": "123456789",
"id_request_client": "test",
"event_type": "end"
}
## Case sent to collection agency
json
{
"id_client": 1000,
"debtornumber": "123456",
"cid": 1184349135,
"mpid": null,
"payment_reference": "123456",
"id_request_client": null,
"event_type": "collection_agency",
"amount_total": 12300,
"event_date": "2024-01-01",
"event_time": "12:00"
}
## Data enrichment
Sent when contact or bank details of a debtor are updated, for example through the self-service pages. Fields ending in _old contain the previous value; fields ending in _new contain the updated value.
json
{
"id_client": 1000,
"debtornumber": "123456",
"cid": null,
"mpid": 1400321802,
"payment_reference": "test",
"id_request_client": null,
"event_type": "data_enrichment",
"email_address_old": null,
"email_address_new": "[email protected]",
"email_address2_old": "[email protected]",
"email_address2_new": "[email protected]",
"mobile_number_old": "+31612345678",
"mobile_number_new": "+31687654321",
"phone_number_old": null,
"phone_number_new": null,
"address_street_old": null,
"address_number_old": null,
"address_number_add_old": null,
"address_postcode_old": null,
"address_city_old": null,
"address_country_old": null,
"address_street_new": "van Coulsterweg",
"address_number_new": "2",
"address_number_add_new": null,
"address_postcode_new": "2952CB",
"address_city_new": "Alblasserdam",
"address_country_new": null,
"birth_date_old": null,
"birth_date_new": "1970-01-01",
"iban_old": null,
"iban_new": "GB33BUKB20201555555555",
"account_owner_old": null,
"account_owner_new": "Collect",
"bic_old": null,
"bic_new": "BARCGB22XXX",
"source": "mycase",
"event_date": "2023-11-10",
"event_time": "12:02"
}
## General correspondence: sequence bounce
Sent when a message in a general correspondence sequence could not be delivered. The channel field indicates the channel on which the bounce occurred.
json
{
"id_client": 1234,
"debtornumber": "D-1000",
"mpid": 1000000000,
"payment_reference": "PAY-123456",
"id_request_client": "REQ-123456",
"event_type": "general_correspondence_sequence_bounce",
"document_id": 123,
"sequence_id": 321,
"sequence_number": 1,
"channel": "email",
"email_address": "[email protected]",
"email_template_id": 100,
"email_subject": "Subject of the email",
"address_street": "Van Coulsterweg",
"address_number": "2A",
"address_city": "Alblasserdam",
"address_postcode": "2952CB",
"address_country": "NL",
"is_registered": true
}
# Getting started
To activate webhooks for your account, provide the following to your Collect contact person:
1. The HTTPS endpoint URL on your server to which all webhooks should be delivered — one endpoint for all event types.
2. Your authentication details, preferably OAuth 2: your token endpoint and client credentials.
3. Whether you want to enable IP whitelisting.
4. The event types you want to receive.
For questions about webhooks or this documentation, contact [email protected].
Authorization
AuthorizationstringheaderrequiredOAuth 2.0 client credentials Grant