Webhooks

Webhooks let Paylead push notifications to your back-office the moment something happens on your Program: a Reward is created, a Consumer’s bank synchronization fails, an Offer is about to expire. From Shift, you declare which URL receives each event type, verify that deliveries genuinely come from Paylead, and inspect the dispatch history. Subscribe to an event when your back-office has to act on it: notify a Consumer, release a payout file, open a support ticket. Polling the API answers “what is true now”; a Webhook answers “something just changed” within seconds. For read-only screens and dashboards, query the API when the user opens them. This page covers the Shift screens. For the technical contract your endpoint implements (payload shape, retry policy, idempotency), see the Webhooks concept. Your system also needs an API key to call back into the Platform.

Set up a Webhook

Each event type is configured independently and points at a single callback URL on your side. In Shift, go to My account > Developers > Hooks. The left side lists every event type Paylead supports.

Pick the event you want to subscribe to

Click the + next to the event. Its configuration panel opens on the right. Each event carries one callback URL at a time, so an event you already subscribed to is greyed out. To fan an event out to several internal systems, point it at one endpoint of yours and dispatch from there.

Enter the callback URL

In the Callback URL field, enter the HTTPS endpoint that will receive the event. The endpoint must accept POST with a JSON body and respond 2xx quickly.

Validate with a test delivery

Click Send test. Paylead immediately posts a payload to the URL with mock data: non-nullable fields carry sample values, nullable fields are left blank.

Save your changes

Click Save. The Webhook is live and Paylead dispatches real events to it from this moment forward.

Nothing is written until you click Save: adding an event, editing a URL, and removing a card all stay local until then. To remove a Webhook, click the bin icon in the header of its card, confirm the dialog, then click Save. The Webhook keeps receiving events until you do. A subscription covers what happens after you save it. When you add one to a live Program, backfill the gap by querying the API for the objects you missed.

Authenticate deliveries

Anyone who discovers your callback URL can post a fake payload to it. Verify each delivery before you act on it. Credentials are set once for the whole Program. On the Hooks page, click Settings in the top right to open the credentials dialog. It offers three independent mechanisms, each enabled by its own checkbox:

Mechanism	Fields
Basic authentication	Username and Password.
HMAC authentication	Secret, 32 characters minimum, alphanumeric only.
Header authentication	Key (appended to a fixed prefix that Shift displays before the field) and Value.

Tick as many as you need, fill in their fields, then click Confirm. Clearing a checkbox deletes that credential.

The Settings button is hidden when your Program signs in through SSO.

Paylead signs every request with HMAC-SHA256 over the raw request body, using the secret from the HMAC authentication block. The signature travels in the X-paylead-signature-256 header as a hex digest, and an optional X-paylead-timestamp header protects against replay. Paylead can also set up mutual TLS on request: see Securing your endpoint.

Verify against the raw request body, not the parsed JSON. Re-serializing the payload changes the bytes and breaks the signature.

Available events

Paylead groups events the same way Shift does, under Cashbacks, Payments, Consumers, and Offers. Subscribe only to the events your back-office reacts to: every extra subscription is traffic your endpoint has to accept, authenticate, and acknowledge in time.

Cashbacks

Event key	Description
`REWARD_CREATED`	A transaction is eligible for a Cashback. The Reward is visible to the Consumer in your app.
`REWARD_VALIDATED`	The Reward has not been cancelled by the merchant. It will be invoiced to the merchant at the end of the month.
`REWARD_PAID_IN`	The Reward amount has left the merchant’s wallet for the Program Manager’s. Shift prints this moment as the `Pool` status.

Payments

Event key	Description
`REWARD_PAID_OUT`	The Consumer pool has been triggered and the Reward transferred to the payment account. Shift prints this moment as the `Paid` status.
`PAYOUT_SUCCESS`	Two wire transfers have been sent to the Program account: one for the sum of the Rewards, one for the associated fees.
`PAYOUT_ERROR`	A transfer error occurred, preventing the Reward from being paid to the Consumer account.
`VENTILATION_FILE_AVAILABLE`	A Ventilation file is available for download.

PAID_IN and PAID_OUT name a movement of money, and Shift prints the matching Reward statuses as Pool and Paid. Check the Status reference before you wire an event to something a support agent will be asked about.

Consumers

Event key	Description
`SCRAPPING_ERROR`	Deprecated. A bank synchronization failure has blocked the Consumer’s transaction feed.
`CONSUMER_REWARD_POOLED`	The Consumer can be notified that a Reward has been deposited in their pool.
`CONSUMER_REWARD_PAID`	The Reward has been paid to the Consumer’s account.
`CONSUMER_REWARD_CANCELLED`	The Reward was cancelled before being paid (refund, dispute, or expiry).
`CONSUMER_REWARD_VALIDATION`	A Reward has been created and is in `Pending validation` status.

SCRAPPING_ERROR is deprecated: do not subscribe to it for a new integration. On a Program that still receives it, it tells you a Consumer stopped feeding transactions to Paylead, so they also stopped earning Cashback without necessarily noticing. Only the Consumer can unblock it. Read the Consumer’s bank synchronization status in Shift to know what to ask for. SCA_REQUIRED and WEBAUTH_REQUIRED need the Consumer to redo an authentication flow, ACTION_NEEDED sends them to their bank’s website, and WRONG_PASS means their stored credentials are stale. See the Status reference for the full list.

Offers

Event key	Description
`NEW_OFFER_AVAILABLE`	A new Offer has been published and is available to Consumers.
`OFFER_ENDING_SOON_DATE`	An Offer is about to expire. The Webhook is sent when the end date is less than 3 days away.
`OFFER_ENDING_SOON_BUDGET`	The Offer budget is close to depletion. The Webhook is sent once the Campaign has consumed 90% of its budget.
`OFFER_CASHBACK_RATE_INCREASE`	The Cashback rate of an Offer has been increased.

Use the two OFFER_ENDING_SOON_* events to warn Consumers while an Offer is still redeemable. The subscription tooltip in Shift announces the budget event at 80% of the budget, while the threshold applied server side is 90%: reconcile on the event, not on the tooltip.

Event logs

Event logs is the landing entry of the Developers menu, reached from My account > Developers. It lists every Webhook delivery attempted on your Program, so it shows exactly what Paylead sent you. Go there when your back-office looks out of sync with the platform, or right after you put a new endpoint live.

Column	Description
Date	When the event was dispatched.
Consumer	The Consumer ID the event relates to, when applicable.
Type	The Webhook event type.
URL	The callback URL that received the event.
Status	The HTTP status code returned by your endpoint. Shift marks any code below `300` as a success.
Next Try	When the delivery will be retried. Reads `Max retries reached` once Paylead stops retrying, and `-` when the status code is never retried.

Four filters scope the history: a keyword search, Filter by type (one event type), Filter by status (a status family, from 1xx to 5xx, plus Others), and the Date From / Date to range. Without filters, every event since the Program launched is shown.

When a delivery fails

Paylead drives the retries on its own, and what happens next depends only on the status code your endpoint returned.

What you see in Next Try	What it means	What to do
A date	Paylead will try again on its own. Server errors qualify, and so do `408`, `425`, and `429`.	Fix the endpoint before that date and the retry lands.
`Max retries reached`	The delivery was retryable, and Paylead has stopped trying.	Re-fetch the affected objects from the API to catch up.
`-`	The code is never retried, which covers most client errors. A `404` or a `403` is a configuration problem on your side, not a transient one.	Fix the URL or the authentication, then use the API to catch up on what you missed.

Each delivery carries a unique event_id. Persist it on your side and dedupe on it, since Paylead may redeliver the same event after retries. See Re-fetch before acting for the recommended pattern.

A day of downtime on your endpoint is a day of events you will not receive twice. Webhooks are a trigger, not a ledger: keep a path that reconciles your data from the API, and use Event logs to scope how far back to reconcile.

Overview

Users management

Catalog

Support

Performance & reporting

Finance & billing

Integration

Set up a Webhook

Authenticate deliveries

Available events

Cashbacks

Payments

Consumers

Offers

Event logs

When a delivery fails

What’s next

Webhooks reference

API reference

​Set up a Webhook

​Authenticate deliveries

​Available events

​Cashbacks

​Payments

​Consumers

​Offers

​Event logs

​When a delivery fails

​What’s next

Webhooks reference

API reference

Set up a Webhook

Authenticate deliveries

Available events

Cashbacks

Payments

Consumers

Offers

Event logs

When a delivery fails

What’s next