Webhook Events
You may consume webhook events to receive real-time notifications about your customers' activity on Ready-to-Launch Bill Pay. Unit uses webhooks to notify your platform when an event occurs, such as when a bill is created or submitted, captured from a file, canceled, paid, payment fails, repaid or refunded, funds settle, archived, or when a vendor is created.
When one of these events occurs, an HTTP POST request is sent to your webhook's configured URL, allowing you to act upon it in real time. This enables you to build responsive integrations, update your systems automatically, and provide better customer experiences.
Unit highly recommends that you make your webhook handlers Idempotent, to ensure events are only handled once on your end.
Setting Up Webhooks
To start receiving webhook events, you'll need to:
- Implement an endpoint on your server to receive and process webhook payloads
- Configure a webhook subscription using one of the methods below:
- Sandbox Environment: Create your webhook subscription via the Unit Dashboard → DEVELOPER menu → Webhooks → Create
- Production Environment: Contact your Unit solution engineer to help set up webhook subscriptions
- Verify webhook signatures to ensure security and authenticity (see Securing your webhooks)
Unit sends POST requests to your webhook's URL from one of the following IP addresses:
| Environment | IP Addresses |
|---|---|
| Sandbox | 54.81.62.38 35.169.213.205 3.234.105.75 |
| Live | 3.209.193.26 54.156.65.95 54.165.224.37 |
Please note that these IP addresses are subject to change.
On production, webhooks that were unresponsive for 7 days will change status to Unavailable and will cease to receive events until they are re-enabled.
On sandbox, webhooks that were unresponsive for 2 days will be changed to status Unavailable.
Available Webhook Events for Bill Pay
Ready-to-Launch Bill Pay clients can subscribe to the following webhook events:
| Event | Description | UI Status Displayed |
|---|---|---|
bill.created | A bill was created. User entered the information manually. | Draft |
bill.capturedFromFile | A bill was created by scanning an uploaded file. | Draft |
bill.paymentfailed | We attempted to complete the transaction but ran into a problem. | Payment Failed |
bill.submitted | The bill is scheduled to be paid on the deduction date. | Scheduled |
bill.fundsdeducted | Funds were drawn from the user’s deposit account and are on their way to the vendor. | In Progress |
bill.paid | The bill payment was successful. Or the user marked that they paid the bill outside of Unit (e.g. cash payment). | Paid / Marked as Paid |
bill.refunded | Funds that were drawn from the user’s deposit account but could not be sent to the vendor were returned back to the user’s deposit account. | Refunded |
bill.archived | The user archived the bill. | Archived |
bill.created
Occurs when a new bill is created.
Example bill.created payload:
{
"data": [
{
"id": "501",
"type": "bill.created",
"attributes": {
"createdAt": "2026-04-15T12:00:00.000Z",
"tags": {}
},
"relationships": {
"bill": {
"data": {
"id": "10001",
"type": "bill"
}
},
"customer": {
"data": {
"id": "10006",
"type": "customer"
}
},
"org": {
"data": {
"id": "5",
"type": "org"
}
},
"vendor": {
"data": {
"id": "20001",
"type": "vendor"
}
}
}
}
]
}
bill.submitted
Occurs when a bill is submitted by the end customer (for example, moving out of draft toward payment).
Example bill.submitted payload:
{
"data": [
{
"id": "502",
"type": "bill.submitted",
"attributes": {
"createdAt": "2026-04-15T12:05:00.000Z",
"tags": {}
},
"relationships": {
"bill": {
"data": {
"id": "10001",
"type": "bill"
}
},
"customer": {
"data": {
"id": "10006",
"type": "customer"
}
},
"org": {
"data": {
"id": "5",
"type": "org"
}
}
}
}
]
}
bill.capturedFromFile
Occurs when bill details are captured from an uploaded file (for example after OCR processing).
Example bill.capturedFromFile payload:
{
"data": [
{
"id": "503",
"type": "bill.capturedFromFile",
"attributes": {
"createdAt": "2026-04-15T12:10:00.000Z",
"tags": {}
},
"relationships": {
"bill": {
"data": {
"id": "10001",
"type": "bill"
}
},
"customer": {
"data": {
"id": "10006",
"type": "customer"
}
},
"org": {
"data": {
"id": "5",
"type": "org"
}
}
}
}
]
}
bill.canceled
Occurs when a bill is canceled.
Example bill.canceled payload:
{
"data": [
{
"id": "504",
"type": "bill.canceled",
"attributes": {
"createdAt": "2026-04-15T12:15:00.000Z",
"tags": {}
},
"relationships": {
"bill": {
"data": {
"id": "10001",
"type": "bill"
}
},
"customer": {
"data": {
"id": "10006",
"type": "customer"
}
},
"org": {
"data": {
"id": "5",
"type": "org"
}
}
}
}
]
}
bill.repaid
Occurs when a bill is repaid (for example, refund or repayment flow completed per product behavior).
Example bill.repaid payload:
{
"data": [
{
"id": "505",
"type": "bill.repaid",
"attributes": {
"createdAt": "2026-04-15T12:20:00.000Z",
"tags": {}
},
"relationships": {
"bill": {
"data": {
"id": "10001",
"type": "bill"
}
},
"customer": {
"data": {
"id": "10006",
"type": "customer"
}
},
"org": {
"data": {
"id": "5",
"type": "org"
}
}
}
}
]
}
bill.paid
Occurs when a bill is paid or recorded as paid (for example after the customer’s payment succeeds or the bill is marked paid in the flow).
Example bill.paid payload:
{
"data": [
{
"id": "507",
"type": "bill.paid",
"attributes": {
"createdAt": "2026-04-15T12:21:00.000Z",
"tags": {}
},
"relationships": {
"bill": {
"data": {
"id": "10001",
"type": "bill"
}
},
"customer": {
"data": {
"id": "10006",
"type": "customer"
}
},
"org": {
"data": {
"id": "5",
"type": "org"
}
}
}
}
]
}
bill.paymentfailed
Occurs when a payment step for a bill fails—for example when deducting funds from the customer fails, or when sending payment to the vendor fails.
Example bill.paymentfailed payload:
{
"data": [
{
"id": "508",
"type": "bill.paymentfailed",
"attributes": {
"createdAt": "2026-04-15T12:22:00.000Z",
"tags": {}
},
"relationships": {
"bill": {
"data": {
"id": "10001",
"type": "bill"
}
},
"customer": {
"data": {
"id": "10006",
"type": "customer"
}
},
"org": {
"data": {
"id": "5",
"type": "org"
}
}
}
}
]
}
bill.refunded
Occurs when a bill is refunded.
Example bill.refunded payload:
{
"data": [
{
"id": "509",
"type": "bill.refunded",
"attributes": {
"createdAt": "2026-04-15T12:23:00.000Z",
"tags": {}
},
"relationships": {
"bill": {
"data": {
"id": "10001",
"type": "bill"
}
},
"customer": {
"data": {
"id": "10006",
"type": "customer"
}
},
"org": {
"data": {
"id": "5",
"type": "org"
}
}
}
}
]
}
bill.fundsdeducted
Occurs when funds for a bill have settled in the passthrough account.
Example bill.fundsdeducted payload:
{
"data": [
{
"id": "510",
"type": "bill.fundsdeducted",
"attributes": {
"createdAt": "2026-04-15T12:24:00.000Z",
"tags": {}
},
"relationships": {
"bill": {
"data": {
"id": "10001",
"type": "bill"
}
},
"customer": {
"data": {
"id": "10006",
"type": "customer"
}
},
"org": {
"data": {
"id": "5",
"type": "org"
}
}
}
}
]
}
bill.archived
Occurs when a bill is archived.
Example bill.archived payload:
{
"data": [
{
"id": "511",
"type": "bill.archived",
"attributes": {
"createdAt": "2026-04-15T12:25:00.000Z",
"tags": {}
},
"relationships": {
"bill": {
"data": {
"id": "10001",
"type": "bill"
}
},
"customer": {
"data": {
"id": "10006",
"type": "customer"
}
},
"org": {
"data": {
"id": "5",
"type": "org"
}
}
}
}
]
}
vendor.created
Occurs when a new Bill Pay vendor is created for a customer.
Example vendor.created payload:
{
"data": [
{
"id": "506",
"type": "vendor.created",
"attributes": {
"createdAt": "2026-04-15T12:26:00.000Z",
"tags": {}
},
"relationships": {
"vendor": {
"data": {
"id": "20001",
"type": "vendor"
}
},
"customer": {
"data": {
"id": "10006",
"type": "customer"
}
},
"org": {
"data": {
"id": "5",
"type": "org"
}
}
}
}
]
}
New event types may be added to the platform over time. Your handler should tolerate unknown type values without failing.
For listing or replaying past events via API, see Events and List Events.