offer_completed webhook

An outbound webhook is an endpoint you implement: this page is the contract of the request Encore sends when one of your users’ offer completions is verified, the response Encore expects back, and the delivery semantics.

For wiring it up (dashboard setup, a runnable signature-verification handler, idempotency, and reconciliation), see the Receive Completion Events guide. For the inbound direction (you forward your own billing’s subscription events into Encore), see Webhook Ingestion: an unrelated flow with different headers and signing.

The request Encore sends

POSTed to the URL you configure at the moment a transaction is marked verified (driven by the advertiser’s conversion postback, not by the user tapping or claiming). It is the only event that credits a user. If you turn on payout updates, Encore can also send offer_payout_booked to the same URL, which never credits one.

POST /webhooks/encore HTTP/1.1
Content-Type: application/json
X-Webhook-Signature: 5a4f2e8c1b3d9e7f6a0c8b2d4e6f1a3c5b7d9e0f...
X-Webhook-Timestamp: 1772044200
X-Webhook-Delivery-Id: d290f1ee-6c54-4b01-90e6-d701748f0851
X-Webhook-Attempt: 1

Headers

Header	Value
`Content-Type`	Always `application/json`.
`X-Webhook-Signature`	Hex-encoded HMAC-SHA256 over the signature base string, keyed by your app’s signing secret (`whsec_...`).
`X-Webhook-Timestamp`	Unix time in seconds at the moment Encore signed. This value goes into the signature base string; use it for a freshness check. Every retry is signed afresh, so this moves between attempts of the same delivery.
`X-Webhook-Delivery-Id`	UUID for this delivery, stable across every retry attempt. For correlating attempts in your logs and in support requests.
`X-Webhook-Attempt`	Which attempt this is, `1` through `6`.

Body

{
  "event": "offer_completed",
  "timestamp": "2026-02-25T18:30:00.000Z",
  "transactionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "userId": "usr_9f8e7d6c-5b4a-3210-fedc-ba0987654321",
  "campaignId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "campaignName": "Audible Premium Plus",
  "payout": 10,
  "reward": { "amount": 200, "unit": "tokens" },
  "actionId": "3f2b8c1e-9d4a-4e7b-8a6f-1c2d3e4f5a6b"
}

Field	Type	Description
`event`	string	Always `"offer_completed"` on this event. Switch on it: the same URL can also receive `offer_payout_booked` if you turn payout updates on, and that one must never credit a reward.
`timestamp`	ISO 8601 string	UTC, milliseconds, trailing `Z`: when Encore generated this delivery. A different format from the `X-Webhook-Timestamp` header (Unix seconds); the header is the one you sign and check for freshness.
`transactionId`	string (UUID)	The Encore transaction that completed. Credit the user once per `transactionId`. To record each paid action of a multi-step offer, key on `transactionId` plus `actionId`, or on `transactionId` alone when `actionId` is absent.
`userId`	string	The end-user identifier as your app supplied it, verbatim: the value you passed to `identify()` or as `userId` on an Encore API call. Encore stores it opaquely and echoes it back unchanged, so it’s the key you look the user up by. If you never supplied an id, this is the SDK’s anonymous per-device id.
`campaignId`	string (UUID)	Stable identifier of the offer the user completed, and the field you join a completion back to the offer you served. It is the same value returned as `offers[].campaignId` by `POST /offers/feed` and as `offers[].id` by `POST /offers/catalog`. Unaffected by renames, locales, and creative rotation.
`campaignName`	string	Human-readable name of the campaign the user completed. A display/logging value, not a stable identifier: campaign names are editable, are never translated, and are unrelated to the `title` returned by `/offers/feed` (which is the creative headline and is translated). Match on `campaignId`, not on either name.
`payout`	number \| `null`	The payout amount associated with this completion, when one was reported. `null` is normal and common: several completion paths carry no amount at delivery time, so code for `null` rather than treating it as an error. No currency field is delivered. A `0` can mean the advertiser priced the conversion in another currency; if you turn on payout updates, `offer_payout_booked` later sends its booked USD figure. Treat your dashboard analytics, not this field, as the source of truth for revenue.
`reward`	object \| `null`	What to credit the user, in your app’s own currency, when your app gives each offer its own value: `{ "amount": integer, "unit": string }`. Per-offer values are turned on per app in the Encore portal, under Settings, in the Rewards section, where you also set the unit name (how values are set). `amount` is a whole number from 0 to 2,147,483,647, and `unit` is the singular or plural unit name from your settings, matching the amount. Always present, and `null` when the transaction carries no value: per-offer values are off, the offer had no value, or the claim didn’t come from a sheet that shows a per-offer reward (today, reward for trying). That last case covers a claim from another sheet, from an SDK before 2.3.1, from the Web SDK or the hosted `/offers` page, and through a click-through link or a redemption. A re-claim from such a source before the brand confirms clears an earlier value, because the latest sheet decides. The value was frozen on the transaction when the user claimed, so it’s the number the card showed, never recomputed, and the same on every delivery for one `transactionId`. When your app pays from the webhook, credit it once per `transactionId`. If your app already paid this prize on the device from `userConfirmedCompletion`, don’t credit it again here: pay each offer from one place, never both. Encore sends no event to take a reward back.
`actionId`	string (UUID)	Omitted when absent. Identifies the paying action this delivery reports, when the completion came from an advertiser conversion. A multi-step offer can pay more than once for one transaction: each paid action sends its own delivery, with the same `transactionId`, its own `actionId`, and its own `payout`. Retries of one delivery repeat its `actionId`. To count each payment, key on `transactionId` plus `actionId`, or on `transactionId` alone when `actionId` is absent; to credit the user, key on `transactionId` alone.

That’s the whole body. The body is exactly the top-level fields in the table, with no app id, creative id, or event id. Only reward is an object; every other field is a plain value. actionId appears only when it has a value, so a handler must not require it. A handler written against a nested req.body.data won’t work; read the fields off the top level. The usr_... shape above is only a placeholder from the test-delivery sample; Encore mints no user ids and adds no prefix.

Signature

The signature base string is the timestamp header and the raw request body, joined by a single dot:

<X-Webhook-Timestamp>.<raw_body>

HMAC-SHA256 that string with your whsec_... signing secret and hex-encode it. The result must equal X-Webhook-Signature. Verify against the exact bytes Encore sent, not a re-serialization; a runnable handler is in the guide.

The response Encore expects

Return any 2xx within 5 seconds. Anything else fails that attempt and Encore retries it.

Behaviour	What happens
Retries	Up to 5 retries after the first attempt, at +5 min, +10 min, +30 min, +2 hours and +6 hours. A delivery that has still not succeeded 8 hours 45 minutes after the conversion is abandoned.
Timeout	5 seconds per attempt. A slower response fails that attempt and is retried.
Non-2xx response	Retried on the schedule above, `4xx` included. Every attempt and its status code is recorded.
Redirects	Deliveries are sent with redirects disabled; a `301`/`302` fails the attempt. Publish the final URL.
Request body	Byte-identical on every attempt. Only `X-Webhook-Timestamp` and the signature over it are recomputed, so verify each attempt against the timestamp it arrived with.
Webhook disabled or deleted	Nothing new is sent. Retries already in flight stop, and nothing is backfilled when you re-enable it.
Ordering	Not guaranteed, and retries make interleaving more likely.
Event id	`X-Webhook-Delivery-Id`, stable across attempts, for correlation only. Key on the body instead: `transactionId` for the user’s credit, and `transactionId` plus `actionId` for each payment (`transactionId` alone when `actionId` is absent).

Delivery is at-least-once

A conversion may arrive more than once, including a delivery your system already processed. A timeout or a missing response tells us nothing about whether your side completed the work, so we retry. Two things protect you, and they cover opposite failures:

Required: credit the user once per transactionId. Take it from the signed request body. Every retry carries the same value, and so does every paid action of a multi-step offer. To record each payment rather than each credit, key on transactionId plus actionId, or on transactionId alone when actionId is absent; retries of one delivery repeat both. Do not key on X-Webhook-Delivery-Id or X-Webhook-Attempt. Both sit outside the signature base string and are not authenticated.
Recommended: return 2xx only once everything the delivery records is durably committed, not on receipt. That is the user’s credit and, if you keep one, the payment record for its actionId. On a later paid action the credit is already a no-op, so the payment record is the only work left to commit. If you acknowledge first and write asynchronously, a failure in that async step is invisible to us: we will not retry, because you already returned 2xx, and the credit or the payment is silently lost.

URL requirements

Requirement	Why
HTTPS	Plain `http://` URLs are rejected. Payloads carry user identifiers.
Publicly resolvable host	An SSRF guard resolves the hostname before every delivery and refuses `localhost` plus private, loopback, and link-local addresses, including a public hostname that resolves to one.
No redirects	Deliveries are sent with redirects disabled.

Receive Completion Events guide: setup, verification handler, idempotency, reconciliation, local testing.
offer_payout_booked webhook reference: a corrected payout for a completion already sent, never a reward.
Webhook Ingestion: the inbound direction, for forwarding your own subscription events into Encore.

Guides

Users

Entitlements

Webhooks

offer_completed webhook

The request Encore sends

Headers

Body

Signature

The response Encore expects

Delivery is at-least-once

URL requirements

​The request Encore sends

​Headers

​Body

​Signature

​The response Encore expects

​Delivery is at-least-once

​URL requirements

​Related

The request Encore sends

Headers

Body

Signature

The response Encore expects

Delivery is at-least-once

URL requirements

Related