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

One event type, 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).

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
}

Field	Type	Description
`event`	string	Always `"offer_completed"`, currently the only event type Encore sends. Still switch on it, so a future event type doesn’t fall through your handler.
`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. Treat this as your idempotency key.
`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. Treat your dashboard analytics, not this field, as the source of truth for revenue.

That’s the whole body. There is no app id, creative id, or event id, and no nesting: the payload is flat, exactly the seven fields above. 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. `transactionId` in the body remains the idempotency key.

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: deduplicate on transactionId. Take it from the signed request body. Every retry of a conversion carries the same value. 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 the credit is durably committed, not on receipt. If you acknowledge first and credit asynchronously, a failure in that async step is invisible to us: we will not retry, because you already returned 2xx, and the user is silently uncredited.

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.
API Reference overview: why a claim is not a conversion, and where completion fits.
Webhook Ingestion: the inbound direction, for forwarding your own subscription events into Encore.

​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