Campaign Webhook

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 displayedon a user's device
• Campaign Click Triggered when a user clicks on a discovered campaign andvisits the campaign action URL

Near real-time event notifications enable you to:

• Instant Analytics Track and analyze your campaign performance inreal-time
• Audio Recognition Based Rewards Issue server-side rewards based on user'saudio 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:

Global Webhook URL

• Set in the Settings section
• Applies to all campaigns by default
• Serves as a central endpoint for all campaign events

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",
  "metadata": {
    "key": "value"
  },
  "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",
  "metadata": {
    "key": "value"
  },
  "timestamp": "2024-01-01T12:00:00Z",
  "viewer_country": "string",
  "viewer_region": "string",
  "viewer_city": "string"
}

Custom Metadata

The metadata field is a key-value pair that comes from the SDK and can be used to identify the user or the device. This field is optional. Please refer to the Metadata Provider section for more details.

Note on Location Information

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

Response Requirements

Your webhook endpoint should:

• Respond with a 2xx status code to acknowledge receipt
• Process events asynchronously if possible to avoid blocking
• 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

Example Implementations

Python (FastAPI)

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"}

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=3000)

NodeJS

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");
});