Webhooks > Introduction

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.

Enabling webhooks

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.


Endpoint
Sample JSON
Add/Update Site
When you add or update a site, you can turn on a webhook for the whole site. A site webhook sends you every invoice and payment notification for that site.
			
{
  "external_id": "12345678",
  "webhook": {
    "active": true,
    "url": "https://mysoftware.com/webhook"
  }
}


		
Add/Update Invoice
When you add or update an invoice, you can turn on a webhook for that invoice. It sends you every notification about the invoice.
			
{
  "external_id": "39772921",
  "webhook_url": "https://mysoftware.com/webhook/{invoice_id}"
}


		

Webhook Events

When a webhook URL is set, Hyfin sends the following messages.

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, email or WhatsApp message was 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) 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.

Retry attempt
Re-sent
#1
5 minutes after initial webhook
#2
1 hour later
#3
2 hours later
#4
24 hours later
#5
48 hours later

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.

Delivery rules

  • The webhook URL must use HTTPS. A URL that uses HTTP is never delivered to and is not retried.
  • A URL that points at a private, loopback or reserved network address is refused. A request that sets one is rejected, and a host name that resolves to one is not delivered to.
  • Redirects are not followed. A 3xx answer counts as a failed delivery, so use the final address as your webhook URL.
  • When 20 webhooks in a row for a site fail every retry, webhooks for that site are paused. While paused, new webhooks are not sent, and they are not sent later either. Contact support to resume them once your endpoint is fixed.