Campaign Webhook

::callout #summary What is Campaign?

#content The user is presented with this when audio recognition through SORI is successful. It can be registered in the SORI console. ::

Overview

SORI API provides webhook functionality to notify your server about campaign-related events in near real-time. By setting up a webhook endpoint in the Campaign's Advanced settings, you can receive notifications for the following events:

  • Campaign Impression: Triggered when a campaign is recognized and displayed on a user's device
  • Campaign Click: Triggered when a user clicks on a discovered campaign and visits the campaign action URL

Near real-time event notifications enable you to:

  • Instant Analytics: Track and analyze your campaign performance in real-time
  • Audio Recognition Based Rewards: Issue server-side rewards based on user's audio recognition status
  • Fraud Detection: Monitor and detect unusual patterns immediately
  • Live Dashboards: Create real-time visualization of your campaign metrics

Setting Up Webhooks

SORI provides two ways to configure webhook endpoints:

  1. Global Webhook URL:
    • Set in the Settings section
    • Applies to all campaigns by default
    • Serves as a central endpoint for all campaign events
  2. Campaign-Specific Webhook URL:
    • Can be configured in each campaign's Advanced settings
    • Overrides the global webhook URL for that specific campaign
    • Useful when different campaigns need different handling

To set up webhooks:

  1. Prepare an HTTP endpoint on your server to receive webhook events
  2. Configure either:
    • A global webhook URL in Settings, or
    • Campaign-specific webhook URLs in individual campaign settings
  3. Ensure your endpoint can handle POST requests with JSON payloads

Event Types

Both impression and click events share the same webhook endpoint. You can distinguish between event types using the event_type field in the payload.

  • Campaign Impression Event
    Sent when a campaign is successfully displayed to a user. For impression events,event_type will be "impression".
  • Campaign Click Event
    Sent when a user clicks on a campaign and is redirected to the campaign action URL. For click events, event_type will be "click".

Handling Webhook Events

When your endpoint receives a webhook event, it will include a JSON payload with the event details. Here are examples for both event types:

For impression events:

{
  "event_type": "impression",
  "material_id": "string",
  "material_name": "string",
  "campaign_id": "string",
  "campaign_name": "string",
  "device_id": "string",
  "platform": "string",
  "timestamp": "2024-01-01T12:00:00Z",
  "viewer_country": "string",
  "viewer_region": "string",
  "viewer_city": "string"
}

For click events:

{
  "event_type": "click",
  "campaign_id": "string",
  "campaign_name": "string",
  "device_id": "string",
  "platform": "string",
  "timestamp": "2024-01-01T12:00:00Z",
  "viewer_country": "string",
  "viewer_region": "string",
  "viewer_city": "string"
}

Note: If the exact information is not available, the value "Unknown" will be provided. This is based on GeoIP estimation and may not always be accurate.

Response Requirements

Your webhook endpoint should:

  • Respond with a 2xx status code to acknowledge receipt
  • Process events asynchronously if needed
  • Handle events idempotently (using the timestamp)
  • Respond within 5 seconds to avoid timeouts

Security Considerations

  • Use HTTPS for your webhook endpoint as possible to ensure data privacy
  • Validate the incoming payload structure
  • Keep your webhook URL confidential

Error Handling

If your endpoint fails to receive events, SORI API Server will:

  • Retry failed deliveries up to 3 times
  • Implement exponential backoff between retries
  • Drop the event after all retries are exhausted

Webhook Implementation Examples

Python (FastAPI) Example

from fastapi import FastAPI, Request

app = FastAPI()

@app.post("/webhook")
async def webhook(request: Request):
    payload = await request.json()
    event_type = payload.get("event_type")

    if (event_type == "impression"):
        # Handle impression event
        # Add code here to process the event, e.g., log to database
        pass
    elif (event_type == "click"):
        # Handle click event
        # Add code here to process the event, e.g., log to database
        pass

    # Respond with a 200 status code
    return {"status": "success"}

NodeJS Example

import express from "express";

const app = express();
app.use(express.json());

app.post("/webhook", (req, res) => {
  const payload = req.body;
  const eventType = payload.event_type;

  if (eventType === "impression") {
    // Handle impression event
    // Add code here to process the event, e.g., log to database
  } else if (eventType === "click") {
    // Handle click event
    // Add code here to process the event, e.g., log to database
  }

  // Respond with a 200 status code
  res.status(200).send({ status: "success" });
});

app.listen(3000, () => {
  console.log("Server is running on port 3000");
});
Table of Contents