Webhooks > Introduction

Webhooks are a great way for your system to receive near real-time updates from Hyfin without the need to constantly polling. When enabled, your system will be notified as soon as an event is trigger within Hyfin.

Enabling webhooks

Webhooks can be enabled on a per site or per invoice basis by assigning a webhook URL when calling the associated endpoints. Here is an example of the json data required to enable webhooks for each endpoint.

Endpoint

Sample JSON

Add/Update Site

When adding or editing a new site, you can enable a webhook at the site level. If a site level webhook is enabled you will receive all invoice and payment notifications for the site.

			
{
  "externalId": "12345678",
  "webhook": {
    "active": true,
    "url": "https://mysoftware.com/webhook"
  }
}

Add/Update Invoice

When adding or editing an invoice, you can enable a webhook at the invoice level and you will receive all notifications related to the invoice.

			
{
  "_id": "39772921",
  "webhookUrl": "https://mysoftware.com/webhook/{invoice_id}"
}

Webhook Events

When a webhook URL is configured, the following messages will be sent.

Action

Detail

Payment

A payment on an invoice reaches a new status, such as captured, settled, voided, refunded or chargebacked. Each status is sent once per payment.

Notification

A text message or email changed delivery state (sent, delivered, read, delayed or failed), or the customer clicked the payment link.

Retries

Your webhook URL must answer with a successful HTTP status code (any 2xx) and should do so within 10 seconds. A non-2xx status, or a connection that cannot be made at all, counts as a failed delivery and the message is re-sent using the following schedule.

Retry attempt

Re-sent

5 minutes after initial webhook

1 hour later

2 hours later

There are three retry attempts at most. Each delay in the table is measured from the previous attempt rather than from the initial webhook, so the third and last attempt is made about three hours after it. If that one also fails the message is not re-sent again.