Send the paywall event

A paywall event tells Hyzl that a person saw your price and left without payment. A server is private software that handles app requests. You can follow this guide or use the AI code assistant setup.

1. Store the Ingest token

The Ingest token permits your server to send paywall events for one app. Create it on that app’s Install page. Copy the token, then pass the clipboard value directly to your server host’s secret command. Store it as HYZL_INGEST_TOKEN.

System	Clipboard reader
macOS	`$(pbpaste)`
Windows PowerShell	`Get-Clipboard -Raw`
Linux	`xclip -selection clipboard -o`

Do not run a clipboard reader by itself if it prints the token. Put the reader inside your host’s secret command. Never put the Ingest token in these places:

A browser or mobile app.
An AI chat.
A code file or .env.example file.
A test, log, or screenshot.

Hyzl shows the token once and stores only a one-way copy. That copy cannot reveal the original token. If the token becomes visible, create a new token on the Install page. A new token replaces the old token at once. Update every server environment that sends events for this app. A server with the stale token gets 401 unauthorized and this message:

That ingest token does not match an app.

2. Send the event

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

Moment	Fit	Reason
The person leaves the paywall without payment	Recommended	The person saw your price and did not buy.
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.
The app collects a phone number before the paywall	Too early	The person did not show clear purchase interest.

If your app cannot detect the exit, send the event when the paywall appears. Do not send it at signup. Your first complete event needs these facts:

A durable identity: userId or stripeCustomerId.
The real consent choice in consent.attested.
A phone number in phoneNumber before Hyzl can contact the person.

A durable identity identifies the same person over time. Email and phone alone cannot prove whether that person paid. For RevenueCat, userId must equal the value passed to Purchases.logIn(). Any other value can make a paid person appear unpaid. For Stripe, send stripeCustomerId when you know it. It must start with cus_. Also set client_reference_id or metadata.userId on the Checkout Session or Payment Link. Use the same userId in the paywall event. Use E.164 format for phoneNumber, such as +13105551212. E.164 is the full number with its country code. Send the person’s real choice in consent.attested. Never set it to true for every person. The examples also use these optional fields:

firstName and email add known contact details.
consent.text records the words that the person saw.
consent.at records the consent time.
eventId makes a retry safe.
occurredAt records when the person left the paywall.
stage describes the point that the person reached.
recoveryUrl supplies a separate link for that person when your link mode needs one.

See the paywall event reference for every available field. Use only the identity fields that apply to your payment provider. Replace every sample value before you send a real event. Send a POST request to this address:

https://yvklwfalxxeslusmnpwi.supabase.co/functions/v1/paywall-event

curl
Node.js
Swift server

curl --request POST \
  --max-time 10 \
  --header "Authorization: Bearer $HYZL_INGEST_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "userId": "user_123",
    "stripeCustomerId": "cus_example123",
    "phoneNumber": "+13105551212",
    "firstName": "Sam",
    "email": "person@example.com",
    "consent": {
      "attested": true,
      "text": "The exact consent words that Sam saw",
      "at": "2026-09-17T14:30:00Z"
    },
    "eventId": "paywall_session_123",
    "occurredAt": "2026-09-17T14:30:00Z",
    "stage": "saw_price"
  }' \
  https://yvklwfalxxeslusmnpwi.supabase.co/functions/v1/paywall-event

// SERVER ONLY. Call this after your app receives its response.
export async function sendHyzlPaywallEvent(user, paywallVisit) {
  const token = process.env.HYZL_INGEST_TOKEN;
  if (!token) return { ok: false, retryable: false };

  try {
    const response = await fetch(
      "https://yvklwfalxxeslusmnpwi.supabase.co/functions/v1/paywall-event",
      {
        method: "POST",
        signal: AbortSignal.timeout(10_000),
        headers: {
          Authorization: `Bearer ${token}`,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          userId: user.id,
          stripeCustomerId: user.stripeCustomerId,
          phoneNumber: user.phoneE164,
          firstName: user.firstName,
          email: user.email,
          consent: {
            attested: user.contactConsent === true,
            text: user.contactConsentText,
            at: user.contactConsentAt,
          },
          eventId: paywallVisit.id,
          occurredAt: paywallVisit.occurredAt,
          stage: "saw_price",
          recoveryUrl: paywallVisit.recoveryUrl,
        }),
      },
    );

    const ok = response.status === 200 || response.status === 202;
    if (!ok) {
      const body = await response.json().catch(() => ({}));
      console.warn("Hyzl", { status: response.status, error: body.error });
    }
    return { ok, retryable: response.status >= 500 };
  } catch {
    return { ok: false, retryable: true };
  }
}

// SWIFT SERVER ONLY. Never put this request or token in an iOS app.
import Foundation

guard let token = ProcessInfo.processInfo.environment["HYZL_INGEST_TOKEN"] else {
  return
}

var request = URLRequest(
  url: URL(string: "https://yvklwfalxxeslusmnpwi.supabase.co/functions/v1/paywall-event")!
)
request.httpMethod = "POST"
request.timeoutInterval = 10
request.setValue("Bearer \(token)", forHTTPHeaderField: "Authorization")
request.setValue("application/json", forHTTPHeaderField: "Content-Type")
request.httpBody = try JSONSerialization.data(withJSONObject: [
  "userId": user.id,
  "stripeCustomerId": user.stripeCustomerId,
  "phoneNumber": user.phoneE164,
  "firstName": user.firstName,
  "email": user.email,
  "consent": [
    "attested": user.contactConsent,
    "text": user.contactConsentText,
    "at": user.contactConsentAt,
  ],
  "eventId": paywallVisit.id,
  "occurredAt": paywallVisit.occurredAt,
  "stage": "saw_price",
  "recoveryUrl": paywallVisit.recoveryUrl,
])

let (_, response) = try await URLSession.shared.data(for: request)
let status = (response as? HTTPURLResponse)?.statusCode
// 200 and 202 mean success. Retry only network errors and 5xx responses.

Do not make the person wait for Hyzl. Let the app continue while your server sends the event. Use a ten-second timeout. Treat 200 and 202 as success. A 5xx response means that Hyzl had a server error. Retry only after a network problem or a 5xx response. A 4xx response means that the request needs a correction. Read the linked error code and fix the request. If the phone number arrives later, send the facts in two steps. Use the same linked userId in both requests.

// Step 1: identify the person before the phone number is known.
await postToHyzl({
  userId: user.id,
  email: user.email,
});

// Step 2: send the phone number and real consent state at the paywall.
await postToHyzl({
  userId: user.id,
  phoneNumber: user.phoneE164,
  consent: { attested: user.contactConsent === true },
});

The second event starts the wait because it carries the phone number and consent.

3. Confirm that the event arrived

The Installation check proves that your server reached Hyzl with an event for this app. The Test text button alone does not count as a completed Installation check. It sends a text from Hyzl, so it tests your Hyzl number and Flow instead of your server code. A test text can arrive while your server integration still sends nothing. Send one normal event for your own test account:

Use your test account’s durable identity and a phone number that you control.
Send the real consent state for that account.
Omit the linked test field or set it to false.
Use a new linked eventId.
Make sure that the response is 202 with a linked status value.
Open the Install page for the same app.
Select Check installation.
Make sure that the Installation check says that Hyzl received the event.

A normal event does not send contact until the Flow wait ends and the app is Live. Do not use a real person’s account for this check.

Get started

Install

Dashboard

Compliance

Reference

Send the paywall event

1. Store the Ingest token

2. Send the event

3. Confirm that the event arrived

​1. Store the Ingest token

​2. Send the event

​3. Confirm that the event arrived

1. Store the Ingest token

2. Send the event

3. Confirm that the event arrived