Use webhooks when your system should hear about payments and messages the moment they happen, instead of asking Hyfin over and over.
Webhooks let Hyfin tell your system about changes as they happen, so you do not have to keep checking. Once you turn them on, Hyfin sends a message to your URL as soon as an event happens.
You turn on webhooks for a whole site or for one invoice by sending a webhook URL to the matching endpoint. Here is the JSON each endpoint needs.
{
"externalId": "12345678",
"webhook": {
"active": true,
"url": "https://mysoftware.com/webhook"
}
}
{
"_id": "39772921",
"webhookUrl": "https://mysoftware.com/webhook/{invoice_id}"
}
When a webhook URL is set, Hyfin sends the following messages.
Your webhook URL must answer with a successful HTTP status code (any 2xx) within 30 seconds. A non-2xx status, a timeout, or a connection that cannot be made at all counts as a failed delivery and the message is re-sent using the following schedule.
There are five retry attempts at most. Each delay in the table is measured from the previous attempt rather than from the initial webhook, so the fifth and last attempt is made about 3.1 days after it. If that one also fails the message is not re-sent again.