A webhook sends a message to an address of your own whenever something happens in your workspace, for example when an order is paid or a subscription is cancelled. Use it to keep another system in sync, such as a tool like Zapier, your accounting or your own server.
Before you start
The page sits under Payments > Settings > Webhooks, in the Developers group. Viewing it needs View Payments. Adding, changing, testing and deleting endpoints needs Update Orders / Customers.
Adding an endpoint
Click the add button to open Add webhook endpoint:
- Under Endpoint, give it an optional Name and enter the Endpoint URL. The address has to be reachable from the internet. Addresses in a private network are refused.
- Under Events, pick what the endpoint should receive. Search events narrows the list, the checkbox of a group selects the whole group, and Select all or Clear all changes everything at once. At least one event is needed.
- Click Create.
The events are grouped by topic:
- Payments: Order paid, Payment processing, Payment failed, Invoice paid, Refund created.
- Subscriptions: Subscription created, Subscription renewed, Subscription cancelled, Subscription payment failed.
- Members: sign-ups, logins, tags added or removed, changed member fields and new contacts.
- Courses & Events, Community and Data & Inbox: completed courses and lessons, event registrations and attendance, posts, levels, badges, inbox messages and tickets.
- Affiliate: new commissions and paid payouts, see the affiliate help.
The signing secret
Right after you create the endpoint, the workspace shows its signing secret once: Copy your signing secret now. Store it on your side, then click Done. It is not shown again.
Every delivery is sent as JSON with the header X-Maio-Signature. It holds an
HMAC-SHA256 of the raw request body, made with your secret, as a lowercase hex
string. Compute the same value on your side and compare it, so you know the
message came from your workspace. The headers X-Maio-Event and
X-Maio-Delivery name the event and the delivery.
To replace the secret, open the endpoint and click Rotate secret. The old secret stops working immediately, so update your endpoint right away.
Testing
Open the endpoint and click Send test. The button changes to Test queued, and a test event arrives at your endpoint within moments. It appears in the delivery log like any other delivery.
The delivery log
The Delivery log tab lists every delivery with its Event, Endpoint, Status, the HTTP status your endpoint answered with, the Attempts and When. Filter it by Delivered, Failed or Pending. The Deliveries section of an endpoint shows its 20 most recent deliveries, with the error of each failed one.
A delivery counts as delivered when your endpoint answers with a 2xx status within 15 seconds. Otherwise it is tried again after 30 seconds, 5 minutes, 30 minutes, 2 hours and 6 hours. Resend sends a delivery again with the same content.
After 20 failed attempts in a row for an event, that event is switched off for the endpoint. If the endpoint answers with 410 Gone, the event is switched off at once. Fix the endpoint, then switch it back to Active.
Switching off and deleting
In the endpoint, the switch toggles between Active and Disabled. A disabled endpoint receives nothing. Delete removes it with all its events after you confirm.
From the API
Apps connected through the API can set up their own endpoints with the
/api/v1/hooks endpoints and an API key with the webhooks:manage scope.
They appear in the list with an API badge, and only their name and status
can be changed here. They have no Rotate secret and no Send test. See
API keys and developer access.