Webhooks

Webhooks are the notifications BlinkyPay sends to your system when something happens in your account, such as a confirmed payment. This screen shows the endpoints that receive those notifications and every delivery made to them, with your server's response and replay. In the menu, open Integrations → Webhooks.

The screen has two tabs: Endpoints and Deliveries. The format of each notification, the list of events and how to verify the signature are in Webhooks, in the integration docs.

#Who can make changes

Anyone on the team sees the endpoints and the deliveries. Creating, editing, activating, deactivating, testing and deleting endpoints, rotating the secret and resending deliveries is only for people with the Owner or Administrator role (see Team). For other roles, the screen hides the buttons and says who can do it.

#Create an endpoint

1. On the Endpoints tab, click New endpoint.
2. In URL, type the address of your system that will receive the notifications. In production, the URL must start with https://.
3. In Events, check the events this endpoint receives. payment.completed and payment.failed come checked. Each event has a short description.
4. Click Create endpoint.

Some events have an old name and a new name, such as payment.completed and charge.paid. The two can't be checked together: checking one clears the other.

When you create the endpoint, recent deliveries that are failing on your other endpoints, for the checked events, are sent through the new one and stop on the old ones.

The screen rejects the URL when:

• an endpoint with the same URL already exists: edit its events instead of creating another one;
• the URL points to a platform domain: use your own system's address;
• the account has reached its limit of active endpoints: deactivate or remove one before activating another.

#Save the signing secret

After you create the endpoint, the Save your signing secret window shows the URL and the Secret.

1. Click Copy and store the secret in your system.
2. Click I've saved it.

The secret is shown only once. The window does not close with Esc or with a click outside it, only with I've saved it or the X.

Each notification arrives signed in the X-BlinkyPay-Signature header. Your system uses the secret to verify the signature before trusting the notification.

#Configured endpoints

Each endpoint shows the URL, the subscribed events and the Active or Inactive badge. The buttons:

• Deactivate and Activate: a deactivated endpoint stops receiving deliveries. Recent deliveries that were still going out through it move to another active endpoint subscribed to the same event; if there is none, they are cancelled. When you reactivate it, it starts receiving the recent deliveries that are failing on the others, like a new endpoint.
• Test: sends a sample notification and shows the result (see below).
• Edit: changes the URL or the events. Click Save. When you change the URL, deliveries that were failing are retried right away. When you uncheck an event, its pending deliveries move to another endpoint subscribed to it.
• Rotate: changes the signing secret.
• Delete: the endpoint stops receiving deliveries right away. Its pending deliveries move to your other active endpoints subscribed to the same event; if there are none, they are cancelled. This cannot be undone. Confirm with Delete endpoint.

#Rotate the secret

The current secret stops working the moment you confirm. Until you put the new one on your server, it rejects the signature of every notification, and paid orders are not marked as paid in your system. Confirm with Rotate and revoke the current secret. The new secret shows up in the New signing secret window, only once.

#Test an endpoint

The test sends a sample payment.completed event to the endpoint's URL. The Webhook test result window shows:

• Received (your endpoint answered with a 2xx code), Timeout (it did not answer in time) or Failed;
• the HTTP code of the response and how long it took;
• the error, when there was one;
• Your endpoint's response;
• the Payload sent, which is the same format that arrives in production;
• the Headers sent.

The test does not show up on the Deliveries tab. There is an hourly limit of tests: when it runs out, the screen says "Hourly limit of webhook tests reached. Try again later."

#Deliveries

The Deliveries tab lists every notification sent, newest first, with the total number of deliveries.

Filter by state (All, Delivered, Pending, Processing, Failed, Exhausted or cancelled), by endpoint (All endpoints) and by event (All events).

The columns are Sent at, Event, Endpoint, Status, Code and Attempts. Code is the HTTP code of your server's last response, in red when it is an error. Attempts shows the attempts made and the maximum. On a phone, the list shows only date, event and state; the rest is in the detail.

#Delivery detail

Click a row to open the detail. It shows the event, the state, the Destination, the Attempts, the Last HTTP, the Payload sent, the Client response and the list of Attempts, each with the HTTP code, the time, the error and the URL used in that attempt.

For a cancelled delivery, the detail gives the reason: the endpoint was deactivated, it was removed, or another endpoint was added. When the delivery was moved, the detail shows to which endpoint and its state there.

#Resend

Resend shows up in the detail of Failed and Exhausted or cancelled deliveries, except the ones already moved to another endpoint. The resend is queued ("Resend queued").

#Default webhook

Settings → Integrations holds the Default webhook, used when a specific endpoint isn't configured. See Settings.