Webhook Ingestion

POST /webhooks/encore is the server-to-server endpoint for forwarding your subscription lifecycle events into Encore. Encore joins each event back to the web exposure it recorded for the same user, which is what powers NCL (incrementality) measurement. This page is the contract: endpoint, authentication, signing, payload schema, responses, and idempotency. For the task-level walkthrough, see Configure Analytics.

This is the inbound direction: your server → Encore. For the outbound direction (Encore calling your server when a user completes an offer), see Offer Completed Webhook. Different headers, a different signing string, and an unrelated purpose; don’t mix the two.

When to use this

Use this if you bill your own subscriptions (for example, Stripe) and want those events in Encore for incrementality measurement. Forward each subscription event from your server as it happens. If your subscriptions run through a source that already notifies us (RevenueCat, Superwall, or App Store / Play server notifications), point those at their dedicated receivers instead; do not also send them here.

Endpoint

POST https://api.encorekit.com/encore/webhooks/encore

One request carries exactly one canonical subscription event. Send events as they happen in your billing system.

Authentication

Requests use the platform’s standard server-to-server HMAC. Send three headers:

Header	Required	Value
`X-API-Key`	Yes	Your app’s publishable key (`pk_live_...` or `pk_test_...`). Resolves which app the event belongs to.
`X-Signature`	Yes	HMAC-SHA256 over the composite signing string (below), keyed by your app’s secret key (`sk_...`), hex-encoded.
`X-Timestamp`	Yes	Unix timestamp in seconds, within ±300 seconds (5 minutes) of Encore’s server time, or the request is rejected with `401`. Use the same value you sign.

Signing a request

The signed string is not the body alone; it is the composite:

<unix_timestamp>.POST./webhooks/encore.<raw_body>

<unix_timestamp> is the exact value you send in X-Timestamp.
The method is the literal POST.
The path is the literal /webhooks/encore. Note this is the path the API serves internally, without the /encore prefix that appears in the public URL. Sign /webhooks/encore, even though you POST to …/encore/webhooks/encore.
<raw_body> is the exact bytes of the JSON body you transmit. Serialize once, then sign and send the identical bytes; do not re-serialize after signing (property reordering or whitespace changes will break the signature).

This buildEncoreHeaders helper is the one signing implementation referenced everywhere in these docs:

import crypto from 'node:crypto';

// The path the API serves internally; the public `/encore` ingress prefix is
// stripped before the signature is checked, so it is NOT part of the signed path.
const SIGNING_PATH = '/webhooks/encore';

/**
 * Build the auth headers for a request to POST /webhooks/encore.
 * Pass the EXACT raw JSON body string you will transmit.
 */
function buildEncoreHeaders(rawBody, { publishableKey, secretKey }) {
  const timestamp = Math.floor(Date.now() / 1000).toString();
  const signingString = `${timestamp}.POST.${SIGNING_PATH}.${rawBody}`;
  const signature = crypto
    .createHmac('sha256', secretKey)
    .update(signingString)
    .digest('hex');

  return {
    'X-API-Key': publishableKey,
    'X-Signature': signature,
    'X-Timestamp': timestamp,
    'Content-Type': 'application/json',
  };
}

// Serialize ONCE, then sign and send the exact same bytes.
const rawBody = JSON.stringify(event);
const headers = buildEncoreHeaders(rawBody, {
  publishableKey: 'pk_live_your_publishable_key',
  secretKey: process.env.ENCORE_SECRET_KEY,
});

await fetch('https://api.encorekit.com/encore/webhooks/encore', {
  method: 'POST',
  headers,
  body: rawBody,
});

Payload

The request body is JSON.

Structure

{
  event_id: string;      // required; unique per event; the idempotency/dedup key
  event_type: string;    // required; Encore-standard verb, e.g. 'did_subscribe' (full list below)
  occurred_at?: string;  // UTC, RFC3339 with trailing Z; defaults to receipt time
  user: {                // required on EVERY event
    app_account_id: string;      // required; the join key; read it client-side with getAppAccountId()
    publisher_user_id?: string;  // your own user id, for cross-checking identify()
  };
  subscription: {        // required on EVERY event
    original_transaction_id: string;  // required; chain anchor, e.g. a Stripe subscription id
    product_id?: string;
    plan?: string;
    price_amount_micros?: number;     // 1,000,000 micros = 1 unit of currency
    price_currency?: string;          // ISO 4217, e.g. 'USD'
    is_trial_start?: boolean;         // true when this event starts a free trial
    store?: string;                   // billing source, e.g. 'stripe'
    country_code?: string;            // ISO 3166-1 alpha-2
  };
  raw_payload?: object;  // your wire payload, preserved verbatim alongside the canonical event
}

Field Reference

Field	Type	Required	Description
`event_id`	string	Yes	Unique id for this event, the idempotency / dedup key: retrying with the same `event_id` collapses to a single event.
`event_type`	string	Yes	One of `did_subscribe`, `did_renew`, `did_cancel`, `did_resubscribe`, `did_expire`, `did_enter_grace_period`, `did_enter_billing_retry`, `did_pause`, `did_change_product`, `did_refund`. Send only these verbs; an unrecognized verb is accepted (`200`) and stored but cannot be projected into subscription-state measurement, so it does not count toward incrementality.
`occurred_at`	string	No	UTC timestamp, RFC3339 with a trailing `Z` (e.g. `2026-06-24T18:30:00Z`). Defaults to receipt time. Must be `Z`: numeric offsets (`+02:00`, even `+00:00`) fail validation, and the event is acknowledged but dropped. JS `toISOString()` is safe; formatters emitting `+00:00` (PHP `DATE_ATOM`) are not.
`user.app_account_id`	string	Yes, on every event	The Encore app account id, read client-side with `getAppAccountId()` and carried through your billing provider. Omitting it fails validation and the event is dropped. See How the join works.
`user.publisher_user_id`	string	No	Your own user id, for cross-checking `identify()`.
`subscription.original_transaction_id`	string	Yes	The subscription chain anchor: your biller’s subscription id. Constant across one subscription’s entire lifecycle.
`subscription.product_id` / `.plan`	string	No	Your product identifier / pricing tier.
`subscription.price_amount_micros`	number	No	Price in micros. Supplying price directly enables revenue-lift measurement on day one.
`subscription.price_currency`	string	No	ISO 4217 currency code.
`subscription.is_trial_start`	boolean	No	`true` when this event starts a free trial.
`subscription.store`	string	No	The billing source (e.g. `stripe`).
`subscription.country_code`	string	No	ISO 3166-1 alpha-2 country code.
`raw_payload`	object	No	Your own wire payload, preserved verbatim for your reference.

Example payload

The canonical example; both required identifiers (user.app_account_id and subscription.original_transaction_id) are present, as they must be on every event:

{
  "event_id": "evt_01HZX...",
  "event_type": "did_subscribe",
  "occurred_at": "2026-06-24T18:30:00Z",
  "user": {
    "app_account_id": "user-123"
  },
  "subscription": {
    "original_transaction_id": "sub_1P9aBcD2eF",
    "product_id": "pro_monthly",
    "plan": "monthly",
    "price_amount_micros": 9990000,
    "price_currency": "USD",
    "is_trial_start": false,
    "store": "stripe",
    "country_code": "US"
  }
}

A later event (for example did_renew) has the same shape and still carries user.app_account_id; only the lifecycle-specific fields differ.

How the join works

Encore links subscription.original_transaction_id (the chain anchor) to user.app_account_id (the persistent person id) on every event, and that link is what resolves a subscription back to the web exposure Encore recorded for the same person. Because the link is (re)written on every event, user.app_account_id must be present on every event, not just the first. An event missing it fails validation and is dropped, so that subscription cannot be attributed. Persist the app account id when you first see a subscription and attach it to every event you forward. Configure Analytics shows this end to end.

Responses

object

{ "success": true, "message": "Received evt_01HZX..." }

The event was authenticated, validated, and forwarded for processing.

object

{ "success": true, "message": "Received (processing deferred)" }

The request authenticated, but an internal error past auth occurred (for example a malformed JSON body or a payload that fails validation, such as a missing user.app_account_id). Encore returns 200 here deliberately, to prevent retry storms.Important: a 200 is not proof of durable storage. The "processing deferred" message specifically means the event was acknowledged but may have been dropped. Treat only the "Received <event_id>" message as a successful ingest; if you see "processing deferred", inspect your payload (most often a validation failure).

object

{ "error": "Invalid signature" }

Authentication failed: missing HMAC headers, a signature mismatch, an unknown key, or an X-Timestamp outside the ±300 second window. Auth failures fail loud (unlike post-auth errors). Note the shape: error responses use Encore’s platform error body, a top-level error message with no success field. Only 200 responses carry the success envelope.

Idempotency

event_id is the dedup key end to end. Re-POSTing an event with the same event_id collapses to a single stored event, so retries are safe.

getAppAccountId()

Returns the persistent Encore app account id for the current user: the value to carry through your billing provider and send as user.app_account_id.

Signature

function getAppAccountId(): string | null

Return Value

Type: string | null

Your own user id if identify() was called.
An auto-generated anonymous id otherwise.
null if the SDK has not initialized yet.

import Encore from '@encorekit/web-sdk';

const appAccountId = Encore.getAppAccountId();

Call Encore.identify(yourStableUserId) so the app account id is your own stable user id rather than an anonymous, per-device id. The same user then resolves to the same app_account_id everywhere, making the join robust across devices and sessions.

getAppAccountId() is the canonical accessor for this use case. getCurrentUserId() returns the same underlying id.

Next steps

Configure Analytics: the quickstart step that uses this contract.
identify(): set a stable user id so the app account id is consistent across devices.

iOS

Android

Web

Bridges

Webhook Ingestion

When to use this

Endpoint

Authentication

Signing a request

Payload

Structure

Field Reference

Example payload

How the join works

Responses

Idempotency

getAppAccountId()

Signature

Return Value

Next steps

​When to use this

​Endpoint

​Authentication

​Signing a request

​Payload

​Structure

​Field Reference

​Example payload

​How the join works

​Responses

​Idempotency

​getAppAccountId()

​Signature

​Return Value

​Next steps

When to use this

Endpoint

Authentication

Signing a request

Payload

Structure

Field Reference

Example payload

How the join works

Responses

Idempotency

getAppAccountId()

Signature

Return Value

Next steps