Campaign Webhook

What is Campaign?

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

  1. Prepare an HTTP endpoint on your server to receive webhook events
  2. Add your webhook URL in the Campaign's Advanced settings section
  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"
}

For click events:

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

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