Webhooks

Webhooks are how Rewarded Media notifies your server about things that happened to your members — they hit a reward threshold, they got flagged for fraud, and so on. Your server receives a real-time HTTP callback with transaction details so you can credit the user, scrub a payout, or update internal state.

Webhooks are fully configurable in the Rewarded Media dashboard: URL, HTTP method, custom headers, body template, signing secret, and which events this webhook subscribes to. At send time we render the body and headers by interpolating template variables (macros) into whatever you've configured.

Prerequisites

• An HTTPS endpoint that returns a 2xx status code
• A shared secret (configured per webhook) used to generate the HMAC signature
• Respond within the timeout budget (see Delivery & Retry Behavior below)

Template Variables

All macros use double curly-brace syntax: {{variable_name}}. You can reference them in any header value or in the body template. For GET requests you don't need to put macros in the URL — every variable is automatically appended as a query-string parameter.

HTTP Methods

• GET — All template variables are automatically appended to the URL as query-string parameters. Any query-string params you already set on the URL are preserved.
• POST / PUT / PATCH / DELETE — The body template is rendered with variable interpolation and sent as the request body. If the body template is left blank, the default payload is a JSON object containing every template variable, including field_signature (but excluding {{signature}}, which is header-only).

Signing the Payload

When a shared secret is configured, the {{signature}} macro expands to an HMAC of the rendered request body, keyed by the shared secret, encoded as lowercase hexadecimal, prefixed with the algorithm name:

sha256=9f3a5e8c...   # SHA-256 (default)
sha512=41d2ab...      # SHA-512

By default, whenever a shared secret is configured, we send the signature in the X-Signature header automatically — you don't need to configure anything extra:

X-Signature: sha256=<lowercase-hex>

To verify on your server: compute HMAC-SHA256(raw_request_body, shared_secret).hexdigest(), strip the sha256= prefix from the header, and compare the two values with a constant-time comparison. For GET requests the body is empty, so the signature is an HMAC over an empty string — if you need authenticated GETs, prefer POST.

Field signature (in-body / in-URL)

{{signature}} is an HMAC of the entire rendered body, so it can't live inside that body — substituting it would change the bytes it signs. If your endpoint needs the signature inside the payload (or in the query string of a GET), use {{field_signature}} instead. It signs a fixed, ordered subset of the event's fields rather than the container that carries it:

message = event ~ transaction_id ~ member_id ~ points_earned ~ completed_at
field_signature = "sha256=" + HMAC-SHA256(message, shared_secret).hexdigest()

# e.g.
message = "completion~1829~user_abc~5~2026-04-21T16:01:42Z"

• Fields are joined with a literal tilde (~) in exactly this order, using the same string values that appear in the payload (completed_at is ISO 8601 UTC, member_id may be empty).
• Output is lowercase hex, prefixed with the webhook's algorithm (sha256= or sha512=) — the same format as {{signature}}.
• Included automatically in the default JSON payload as field_signature, and appended to GET query strings. In a custom body template, place it wherever you like.
• Because event is signed, a fraud_flagged payload can't be replayed as a completion.
• It does not cover the revenue fields — verify those with the whole-body X-Signature header if you rely on them. Both are sent when a secret is set; use whichever fits your endpoint.

// Body template
{"event":"{{event}}","tx":"{{transaction_id}}","user":"{{member_id}}",
 "points":"{{points_earned}}","at":"{{completed_at}}","sig":"{{field_signature}}"}

// Verify (Node)
const msg = [b.event, b.tx, b.user, b.points, b.at].join('~');
const expected = 'sha256=' + crypto.createHmac('sha256', SECRET).update(msg).digest('hex');
if (!timingSafeEqual(Buffer.from(expected), Buffer.from(b.sig))) return res.status(401).end();

Delivery & Retry Behavior

• Connect timeout: 5 seconds. Read timeout: 10 seconds.
• Delivery is retried once per minute for up to 15 attempts on any failure — network errors, timeouts, or non-2xx HTTP responses. After 15 attempts the delivery is considered permanently failed.
• Every attempt (success or failure) is recorded in the delivery log with the response status or error message.
• Use {{transaction_id}} to deduplicate on your side in case of redelivery.