Webhooks

Have Inkwave tell another system the moment something happens in your publication, such as a new subscriber or a sent post.

What a webhook is

A webhook is a message Inkwave sends to an address of yours whenever something happens, like a reader subscribing. Tools such as Zapier and Make, or your own server, can receive these messages and act on them, for example to add the reader to your CRM.

Each address you add is called an endpoint. You manage them under Settings, Webhooks. Only the owner and admins can open this page.

Creating an endpoint

Click Create Webhook Endpoint.
Enter the Endpoint URL: the web address that should receive the messages, such as https://example.com/webhook.
Add a Description so you can recognise it later, for example "New subscribers to Zapier".
Leave Webhook Status on to start receiving messages straight away.
Under Event Types, pick at least one event. Hover over the information icon on an event to see when it fires.
Click Create Webhook.

Events you can choose

Event	Fires when
`subscription.created`	A new reader joins your list. If your publication asks readers to confirm their email, it fires once, when they confirm.
`subscription.deleted`	An active subscriber unsubscribes.
`subscription.upgraded`	A free subscriber upgrades to a paid tier.
`subscription.downgraded`	A paid subscriber goes back to free and has no paid tier left.
`subscription.tier.created`	A subscriber is added to a paid tier.
`subscription.tier.deleted`	A subscriber is removed from a paid tier.
`post.sent`	A newsletter post is sent to subscribers.
`survey.response_submitted`	A reader submits a survey response.
`poll.response_submitted`	A reader answers a poll.
`invoice.payment_succeeded`	A reader's payment for a paid subscription succeeds.
`invoice.payment_failed`	A reader's payment for a paid subscription fails.

An endpoint only receives the events you picked. Messages go only to endpoints whose status is Active.

What each message looks like

Every message is a POST request with a JSON body that has four parts:

event_type: which event it is, such as subscription.created
created_at: when the message was made
is_test: true for a test event, false for a real one
data: the details of what happened

Two headers come with it: X-Inkwave-Event, which repeats the event type, and X-Inkwave-Signature, which lets you check the message really came from Inkwave.

Checking the signature

Open an endpoint from the list to see its Endpoint Secret. Use the eye icon to show it and the copy icon to copy it. Keep it private.

The signature is an HMAC-SHA256 of the exact request body, made with your secret and written in hexadecimal. To check a message, compute the same value on your side from the raw body you received and compare it with the X-Inkwave-Signature header. If they don't match, ignore the message.

To replace the secret, click the button beside it (its tip reads "Generate a new signing secret") and confirm with Rotate. Messages are signed with the new secret immediately, so your endpoint will reject them until you update the secret there. Copy the new one as soon as it appears.

Testing an endpoint

Open the endpoint and click Send Test Event. Pick one of its event types and click Send Test. A sample message goes to your address with is_test set to true, and the result shows in the list on the page within a few seconds.

Checking deliveries

The Current webhooks list shows, for each endpoint, whether it is Active or Inactive, how many event types it has, how many delivery attempts there have been, and its error rate.

Open an endpoint to see every attempt: Pass or Fail, the event type, a message ID and the time. Choose View details on an attempt to see the HTTP status your server answered with, whether it was a Test or Live message, and the full request and response bodies.

Your endpoint should answer with a status in the 200s within 10 seconds. If it answers with a 5xx, a 408 or a 429, is too slow, or can't be reached, Inkwave tries the event again a few times over the next few minutes. Any other answer, such as a 404, is not retried. If no try succeeds, the attempt is listed as Fail and the event isn't sent again, so make sure your endpoint is up and answering before you rely on it.

Editing, pausing and deleting

From the menu on an endpoint, choose Edit to change its address, description, status or events, then click Save Changes. To stop messages without losing the endpoint, turn off Webhook Status.

Choose Delete to remove an endpoint for good. Deliveries to it stop immediately, and this can't be undone.

Plans and pauses

If your plan doesn't include webhooks, Create Webhook Endpoint is switched off and the page says "Your plan doesn't include webhooks. Your endpoints are kept." While that is the case:

no events are sent, and the page shows "Events aren't being sent on this plan."
events that happen during this time are not saved up to send later
you can still edit endpoints and switch them off, but you can't switch one back on or send a test

Upgrade under Settings, Billing & Plan, and your active endpoints start receiving events again.

Your plan may also limit how many endpoints you can have, active or not; at the limit, creating another is refused with a message saying how many your plan allows.

Nothing is sent while your publication is suspended either.

Troubleshooting

Every attempt fails: open an attempt with View details and check the HTTP status and response body. A status outside the 200s means your server refused or errored. Check that the address is right and publicly reachable.

My server says the signature is wrong: make sure you compute it from the raw request body exactly as received, before any parsing, and with the current secret. If you rotated the secret, update it on your server.

Nothing arrives at all: check that the endpoint is Active, that the event you expect is ticked, and that your plan includes webhooks.

"Must be a valid URL": enter the full address, starting with https://.

An event failed and never came back: once every try has failed, the event isn't sent again. Fix the problem on your server, then use Send Test Event to check that the next message gets through.

Reference

For developers: every event and its fields, and verifying signatures and how delivery works.

On this page