Offer Event Webhooks

Joining the Beta

We are currently in a pilot phase. To participate in this phase as a beta tester, reach out to your representative. When you are enrolled in the pilot, you will need to provide the url where you'd like to receive webhook payloads. You will also need a secret key for authenticating the webhooks. See Authentication below.

Structure

A POST request will be made to your webhook url. Here is an example of the request body:

{
    "type": "offer.removed",
    "timestamp": "2024-07-11T20:26:10.344522Z",
    "data": {
        "offerId": "123456789456123"
    }
}

Field	Explanation
type	The type of change that has occurred.
timestamp	The unix time when the request was generated. Expect a slight delay between the time that the request is generated and the time it is received.
data.offerId	The unique id of the offer. See the id field in the Offer API Response.

Available Webhooks

Type	Explanation
offer.removed	Sent when an existing offer is removed and no longer available to new players. Players that have already started the offer will still be able to continue and finish. New players should not be shown the offer, as they are not eligible and will not be credited.
offer.updated	Sent when campaign metadata has been updated and/or changes have been made to the associated campaign's adcopy
offer.created	Sent when an offer id has been superseded for an existing campaign, or when a net new campaign ID is enabled for an app ID

Retrying Failed Requests

When a webhook request is sent, a response with a 2xx-series status code is expected. If the response includes any other status code, the request will be retried up to three times. Be sure to account for this to avoid double-rewarding players.

Authentication

The webhook request headers contain a Signature. This is calculated by hashing the request body and the secret key using the HMAC-SHA256 algorithm. To authenticate the request, hash the request body and the secret key using the HMAC-SHA256 algorithm. Compare the result to Signature value to confirm a match.

Examples:

PHP/LaravelNodeJS

Route::post('/webhook-receiver', function () {
    $receivedSignature = request()->headers->get('Signature');

    $expectedSignature = hash_hmac('sha256', request()->getContent(), 'secret-key');

    if ($expectedSignature === $receivedSignature) {
        return response()->noContent(200);
    } else {
        return response()->noContent(401);
    }
});

const express = require('express');
const crypto = require('crypto');

const app = express();
const port = 3000;

app.use(express.json());

app.post('/webhook-receiver', (req, res) => {
    const receivedSignature = req.headers['Signature'];

    const postData = JSON.stringify(req.body);
    const expectedSignature = crypto.createHmac('sha256', 'secret-key').update(postData, 'utf8').digest('hex');

    if (expectedSignature === receivedSignature) {
        res.status(200).send();
    } else {
        res.status(401).send();
    }
});

app.listen(port, () => {
    console.log(`Server running on port ${port}`);
});