Paywall event reference

A server is private software that handles app requests. A paywall event is a request from that server after a person leaves your paywall. It gives Hyzl the facts that it needs for recovery. Start with Send the paywall event for a short setup guide. You can also use an AI code assistant.

Address

POST https://yvklwfalxxeslusmnpwi.supabase.co/functions/v1/paywall-event
Authorization: Bearer <your server key>
Content-Type: application/json

Protect the ingest token

The ingest token is the secret that permits your server to send paywall events. On the Install page, this appears as Server key.

Generate the ingest token on the Install page.
Copy the key to your clipboard.
Store it as HYZL_INGEST_TOKEN in your server environment.
Use your platform’s secret command to read the clipboard.

On macOS, use $(pbpaste). On Windows, use Get-Clipboard -Raw. On Linux, use xclip -selection clipboard -o. Do not put this key in a chat, code file, test, log, or screenshot. Anyone with the key can send events for your app and use your Hyzl number. If the key becomes visible, generate a new key on the Install page. A new key replaces the old key at once.

Choose the right moment

Send the event after a signed-in person sees your price and leaves without payment. This moment starts recovery.

Where	Fit	Why
The paywall is shown and they leave without buying	Recommended	They saw your price and did not buy. Recovery fits this moment.
The paywall appears	Good	The Flow wait gives the person time to finish payment.
Signup completes	Too early	The person did not see your price yet.
A phone number is collected, before the paywall	Too early	Same problem, one step sooner.

If you collect the phone number later, send another event with the same userId. The event with the phone number and consent starts the wait.

Fields

Field	Requirement	What happens without it
`userId` or `stripeCustomerId`	Required (one of them)	`400 missing_durable_id`. Email and phone alone cannot verify a payment, so we reject the event rather than risk texting someone who already paid. `userId` must be the same id your app passes to `Purchases.logIn()`. A `stripeCustomerId` must start with `cus_`. Minimum 5 characters.
`phoneNumber`	Required by the final step. May arrive on a later event.	Nobody can be contacted. The person is stored and shown as waiting for a phone number. E.164, e.g. `+13105551212`.
`consent.attested`	Required. Send the real state of whatever you collect, including `false`.	Absent leaves whatever we already hold for this person unchanged. An explicit `false` REVOKES consent: outreach stops immediately. A non-boolean is `400 invalid_consent`.
`consent.text`	Optional	The exact wording you showed. Stored with the person as your TCPA evidence trail.
`consent.at`	Optional	When they ticked it. ISO 8601.
`email`	Optional	A positive-only finder. A match resolves a Stripe customer for us to check; email never keys the person, because it is reassigned and is not unique in Stripe. Send it exactly as it is stored on your side — Stripe matches customer email case-sensitively, so we query both your spelling and its lowercase form.
`firstName`	Optional	The text uses “there” instead of their name. Never used to match people.
`eventId`	Optional	Send one to make retries safe. A repeat of an id we have processed is a `200` no-op.
`occurredAt`	Optional	The wait is measured from when we receive the event instead of when it happened. ISO 8601 or epoch milliseconds.
`startTimerAt`	Optional	A later moment when the timer must start. Hyzl uses the later of `occurredAt` and `startTimerAt`. Re-sending it resets the timer.
`stage`	Optional	The text uses generic wording. `saw_value`, `saw_price` and `pre_offer` tailor it; any other label passes through as context.
`price`, `currency`	Optional	`{price}` renders blank and the phrase around it is dropped.
`recoveryUrl`	Optional	Your own https link, texted verbatim. We never read, change or add anything to it. A later value replaces an earlier one. Not https, or with embedded credentials, or over 2048 characters: `400 invalid_recovery_url`.
`percentOff`	Optional	Your win-back percent, a whole number 1–90. Outside that: `400 invalid_percent_off`.
`offerLinks`	Optional	For Auto mode: the discount tiers your checkout can honour for this person, as whole percents 0–90 mapped to your own https links, e.g. `{"0": "https://…/full", "33": "https://…/33", "66": "https://…/66"}`. `"0"` is full price. Hazel may move the person to one of these tiers (never above your app’s offer, never below what they already hold) and then texts that tier’s link. Each link follows the `recoveryUrl` rules. A later event with `offerLinks` replaces them. Not an object, a key that is not a whole percent 0–90, or a bad link: `400 invalid_offer_links`.
`context`	Optional	A short string of facts about this person that helps the AI rep, e.g. their onboarding answers (“Goal: run a 10K. Blocker: price.”). Trimmed; up to 1000 characters. Given to the AI rep on texts and calls as information about the person, never as instructions, so send facts rather than directions. A later event with `context` replaces it. Not a string, or over 1000 characters: `400 invalid_context`.
`detail`	Optional	A short line for your message templates, used as `{detail}` in Flow texts, e.g. the trip they searched (“LA → Tokyo, business class, November”). Trimmed; up to 80 characters; no links. The AI rep also sees it as a fact about the person. A later event with `detail` replaces it. Not a string, over 80 characters, or containing a link: `400 invalid_detail`.
`test`	Optional	For trying the flow, not for real signups. `true` texts the number on this event within a minute, skipping the wait, the paid check and your app’s on/off switch. It must include `phoneNumber` on the same event (`400 test_requires_phone`) and it never falls back to a number we already hold — otherwise a test against an existing record would text a real customer. Send a number you control. Never send `true` on a real signup.

Hyzl ignores fields that do not appear in this table.

Match each person to a payment

For RevenueCat, userId must equal the value that your app gives to Purchases.logIn(). The wrong value can make a person appear unpaid after a purchase. For Stripe, send stripeCustomerId when you know it. Also set client_reference_id or metadata.userId on the Checkout Session or Payment Link. Use the same userId in the paywall event. Hyzl checks each available Stripe identifier before contact. If a Stripe check fails, Hyzl waits instead of treating the person as unpaid.

Give Hazel a link for each offer

Use offerLinks if your checkout has a different secure link for each allowed discount. Each key is a whole discount percent from 0 through 90. The 0 key means the regular price.

{
  "offerLinks": {
    "0": "https://example.com/checkout/full-price",
    "25": "https://example.com/checkout/25-off",
    "50": "https://example.com/checkout/50-off"
  }
}

Hyzl uses only the links that you send for that person. Each link must follow the same rules as recoveryUrl. Consent is a person’s recorded permission for contact by text or call. Send the real state of your current consent choice. If you do not ask for consent, add an unchecked box beside your optional phone field. Edit this example for your business and legal requirements. Example wording:

I agree that {Your company} and its service providers may contact me by phone call and text message at the number provided, including with automated or AI-assisted technology, about my account and related offers. An AI may answer calls, and calls may be recorded and transcribed. Consent is not a condition of purchase. Message frequency varies. Message and data rates may apply. Reply STOP to opt out. Reply HELP for help. {Terms link} · {Privacy link}

Replace the placeholders with links to your Terms and Privacy Policy. Send the real consent state as consent.attested, either true or false. Never set it to true for every person. Keep the box clear by default. Keep the phone field optional. Hyzl stores a person without consent, but Hyzl does not contact that person.

Examples

curl

curl -X POST https://yvklwfalxxeslusmnpwi.supabase.co/functions/v1/paywall-event \
  -H "Authorization: Bearer {{YOUR_INGEST_TOKEN}}" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_123",
    "phoneNumber": "+13105551212",
    "email": "person@example.com",
    "firstName": "Sam",
    "stage": "saw_price",
    "consent": { "attested": true },
    "eventId": "paywall_abc123"
  }'

Node

// Call this at the paywall, when the person does not buy.
await fetch("https://yvklwfalxxeslusmnpwi.supabase.co/functions/v1/paywall-event", {
  method: "POST",
  headers: {
    Authorization: "Bearer {{YOUR_INGEST_TOKEN}}",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    // Must be the same id you pass to Purchases.logIn()
    userId: user.id,
    phoneNumber: user.phoneE164,
    email: user.email,
    firstName: user.firstName,
    // The real state of your consent checkbox, not a hardcoded true
    consent: { attested: user.contactConsent === true },
    eventId: paywallView.id,
  }),
});

Swift

// Call this at the paywall, when the person does not buy.
var request = URLRequest(url: URL(string: "https://yvklwfalxxeslusmnpwi.supabase.co/functions/v1/paywall-event")!)
request.httpMethod = "POST"
request.setValue("Bearer {{YOUR_INGEST_TOKEN}}", forHTTPHeaderField: "Authorization")
request.setValue("application/json", forHTTPHeaderField: "Content-Type")
request.httpBody = try JSONSerialization.data(withJSONObject: [
  // Must be the same id you pass to Purchases.logIn()
  "userId": user.id,
  "phoneNumber": user.phoneE164,
  "firstName": user.firstName,
  // The real state of your consent checkbox, not a hardcoded true
  "consent": ["attested": user.contactConsent],
  "eventId": paywallView.id,
])

let (_, response) = try await URLSession.shared.data(for: request)

Send in two steps

// Step 1, when you first know the person. No phone number yet.
await postToHyzl({ userId: user.id, email: user.email });

// Step 2, at the paywall, once you have the phone number and consent.
// Same userId. This step starts the wait.
await postToHyzl({
  userId: user.id,
  phoneNumber: user.phoneE164,
  consent: { attested: user.contactConsent === true },
});

Responses

Status	`error`	Meaning
202	None	Stored. `outcome` is `created` for a new person or `joined` for an existing person.
200	None	A repeated `eventId`. `outcome` is `duplicate`, and Hyzl makes no change.
400	`malformed_body`	The body was not a JSON object.
400	`invalid_phone`	`phoneNumber` was sent but could not be read as E.164.
400	`invalid_consent`	`consent` was not an object, or `consent.attested` was not a boolean.
400	`missing_durable_id`	No `userId` and no `cus_…`. Email or phone alone is not enough.
400	`invalid_recovery_url`	`recoveryUrl` was not a valid https URL.
400	`invalid_percent_off`	`percentOff` was not a whole number 1–90.
400	`invalid_offer_links`	`offerLinks` was not an object of whole percents 0–90 to https links.
400	`invalid_context`	`context` was not a string, or was over 1000 characters after trimming.
400	`invalid_detail`	`detail` was not a string, was over 80 characters after trimming, or contained a link.
400	`invalid_occurred_at`	`occurredAt` or `startTimerAt` could not be read, or was outside 2020–2100. Sending Unix seconds where milliseconds are expected lands here.
400	`test_requires_phone`	`test: true` without a `phoneNumber` on the same event.
401	`unauthorized`	No token: `Send your ingest token as Authorization: Bearer <token>.`
401	`unauthorized`	Wrong token: `That ingest token does not match an app.`
405	`method_not_allowed`	Use POST.
501	`sdk_not_available`	`sdk-event` only. See below.
500	`internal_error`	Ours. Retry.

Treat 200 and 202 as success. A 202 response also includes these fields:

person_id: the Hyzl record for the person.
status: the person’s current recovery state.
contactable: whether Hyzl has a phone number.
consent_attested: the consent state that Hyzl stored.
next_action_at: the next planned action time, or null.

A 202 response means that Hyzl stored the event. It does not mean that Hyzl sent a text.

Send from your server

Do not send this event from a browser or mobile app. A public app can expose the ingest token to other people. The future sdk-event endpoint returns 501 sdk_not_available and is not deployed. Send all paywall events to paywall-event from your server.

What happens after the event

Hyzl stores the event.
Hyzl waits for the first step in your Flow.
Hyzl checks the payment provider before each step.
Hyzl stops recovery if the person paid or sent STOP.
Hyzl sends the step if the person remains eligible.

The default Flow waits five minutes, then sends one text. Its later text steps wait one day and three days. Quiet hours use the time zone for your app, not the person’s location. The default quiet hours are 9 p.m. to 9 a.m. in that app time zone. Hyzl holds scheduled texts until quiet hours end. Call steps use their own calling window. Outbound calls are off by default and only call United States and Canada numbers. A reply pauses the Flow for 24 hours while Hazel talks with the person. Hyzl resumes the Flow only after the conversation stops and the person remains unpaid.

Get started

Install

Dashboard

Compliance

Reference

Paywall event reference

Address

Protect the ingest token

Choose the right moment

Fields

Match each person to a payment

Give Hazel a link for each offer

Examples

curl

Node

Swift

Send in two steps

Responses

Send from your server

What happens after the event

​Address

​Protect the ingest token

​Choose the right moment

​Fields

​Match each person to a payment

​Give Hazel a link for each offer

​Consent

​Examples

​curl

​Node

​Swift

​Send in two steps

​Responses

​Send from your server

​What happens after the event

Address

Protect the ingest token

Choose the right moment

Fields

Match each person to a payment

Give Hazel a link for each offer

Consent

Examples

curl

Node

Swift

Send in two steps

Responses

Send from your server

What happens after the event