Webhooks

A webhook is a message Toki sends to a web address you choose, right when something happens in your loyalty program: a member's points balance changes, a member reaches a tier, a paid membership renews. Your developer uses these messages to keep your other tools in step with Toki, such as a CRM, a help desk, or a custom app. This article is written for you and for the developer who will set webhooks up.

How webhooks work

Your developer builds an endpoint: a web address on your side that can receive messages.
You subscribe that endpoint to an event topic through the Toki API.
Each time the event happens, Toki sends a message to the endpoint, confirms it arrived, and tries again if it didn't.

If you want to react to these same events without writing any code, Workflows can do that inside Toki. Webhooks are for the cases where the reaction has to happen in a system outside Toki.

Events you can subscribe to

Each subscription covers one topic. Use the topic names exactly as shown.

Topic	When Toki sends it
`TRANSACTION_CREATED`	A points transaction is recorded for a member, so their balance goes up or down.
`PAID_MEMBERSHIP_SUBSCRIBED`	A customer starts a paid membership.
`PAID_MEMBERSHIP_RENEWED`	A paid membership renews.
`PAID_MEMBERSHIP_CHANGED`	A member switches their paid membership to a different plan.
`PAID_MEMBERSHIP_CANCELLED`	A paid membership is cancelled.
`TIER_EARNED`	A member reaches a tier.
`TIER_LOST`	A member drops out of a tier.

Every message carries the details of the event, such as the member involved and the tier or membership concerned. Your developer can read the exact contents of real deliveries on the monitoring page in the portal (see Webhook monitoring).

Before you start

Generate your Toki API Key. Webhook subscriptions are created with it, and every delivery is signed with it. Open Integrations and find the Toki API Key card. See Integrations and your API key.
Use a secure endpoint. The endpoint address must start with https://. Toki sends webhooks to secure addresses only.

Set up a subscription

Subscriptions are created through the Toki API, not on a page in the portal. Chat with us and we will share the API reference with you and your developer.

In short, your developer:

Authenticates with your Toki API Key.
Creates a subscription by giving a topic from the table above and the endpoint address.
Repeats this for each topic you want to receive. One subscription covers one topic and one endpoint.

Your developer can also list your subscriptions and remove the ones you no longer need, using the same API. Every active subscription appears on the Webhook Subscriptions page in the portal, which you reach from Integrations by clicking Webhooks Logs under Toki API Key.

What your endpoint receives

For every event, Toki sends one message to your endpoint, in JSON format. Two headers come with it:

Header	What it is for
`X-Toki-HMAC-SHA256`	A signature of the message, computed with your Toki API Key. Your developer can recompute it on your side to confirm the message really came from Toki and was not changed on the way.
`X-Toki-Webhook-Id`	A unique ID for this webhook. If the same webhook is delivered more than once, the ID stays the same, so your developer can skip duplicates.

The signature always uses your current Toki API Key. If you click Regenerate on the Toki API Key card, deliveries are signed with the new key from that moment on, so give the new key to your developer right away.

Delivery and retries

Toki counts a message as delivered when your endpoint answers with a success status code (any code from 200 to 299). Your endpoint needs to answer directly: Toki treats a redirect as an unsuccessful attempt.

If an attempt is unsuccessful, because the endpoint was unreachable, answered with an error, or redirected, Toki tries again on its own. It makes up to 7 attempts in total and waits longer before each one, starting at about a minute and growing to a few hours between the last attempts. All attempts together span roughly seven hours, so a short outage on your side doesn't lose the message.

On the monitoring page, a webhook shows as Pending until your endpoint accepts it, then as Sent.

Monitor deliveries

The portal keeps a record of every subscription, every webhook, and every delivery attempt, including the status code and response your endpoint returned. Open Integrations and click Webhooks Logs under Toki API Key to get there. The details are in Webhook monitoring.

Integrations and your API key: generate or regenerate the Toki API Key that authenticates the API and signs webhooks.
Webhook monitoring: check subscriptions, delivery status, and the response your endpoint returned.
Workflows: react to the same events inside Toki, with no code.
How points work: the transactions behind TRANSACTION_CREATED.
Membership tiers: the tiers behind TIER_EARNED and TIER_LOST.
Paid memberships: the memberships behind the PAID_MEMBERSHIP_* topics.