External Vendors Campaign Engagement Metrics

📘

This capability might require set up from Optimove side. Please contact support if experiencing any server issues

Overview

This document serves as a comprehensive guide for integrating 3rd-party vendor metrics into Optimove. Using this new capability is an enhancement of the current use of API endpoint UpdateCampaignInteractions, providing enhanced capabilities and unlocking limitations.

Endpoint

Base URL

Campaign engagement events should be reported to this endpoint:

metric-<tenantID>.optimove.net/api/saveEvent

[tenantID] should be provided by Optimove support teams.

Authentication Requirements

To authenticate requests, include the following headers:

Header Name: X-Optimove-Signature-Version

Content: “1”

Header Name: x-optimove-signature-content

Content: The request body hashed using HMAC with SHA-256 and the tenant’s token as the secret key.

• Cryptographic Hash Function: SHA-256
• Output Format: Hexadecimal
• Input Plain Text: JSON-stringified request body
• Secret Key: Tenant token

Example HMAC Generation

Use an online tool such as Devglan HMAC SHA-256 Tool:

1. Set "Cryptographic Hash Function" to SHA-256.
2. Input the plain text as the JSON-stringified request body.
3. Use the tenant token as the secret key.

Read more about HMAC authentication with Server-Side events here

Request Structure

Body Format

The request body may contain a single event or an array of events. Each event must adhere to the following structure. Each event’s payload must comply with the defined structure, ensuring consistency and interoperability. No additional attributes will be processed.

{
    "event": string [required],
    "category": "metric" [required],
    "timestamp": string, in UTC [required], (max 7 days ago)
	  "customer": string [either this or "visitor" are required values],
	  "visitor": string [either this or "customer" are required values],
    "context": {
        "send_id": string [required],
        "execution_gateway": string [required] [Represents channel name],
        "execution_date": string, in UTC [required] (max 7 days ago)
    }
}

Important Notes

• At least one of customer or visitor must be valid.

Example Request Body

[
    {
        "event": "open",
        "category": "metric",
        "customer": "kuku4",
        "visitor": "9eec52b4-5a05-4d02-835a-086374508c06",
        "timestamp": "2024-12-05T12:00:00",
        "context": {
            "execution_gateway": "my_vendor",
            "send_id": "22222",
            "execution_date": "2024-12-05"
        }
    }
]

Get all available channels here -

https://developer.optimove.com/reference/get_actions-getexecutionchannels

Field Definitions

Event-Level Fields

Context-Level Fields

Response Structure

Success Response

HTTP Status Code: 200

Body:

{
    "status": "SUCCESS",
}

Failure Responses

Example response:

HTTP Status Code: 401

{
    "status": "FAIL",
    "message": "Failed to authenticate server webhook request"
}

Error Handling and Validation

• Missing/Invalid Data: Reject invalid events with detailed error messages.
• Data Integrity: Validate tenant ID, field formats, and mandatory attributes.

Allowed Values

1. “event” - [Note - this is case-sensitive]
   1. Delivered
   2. open
   3. click
   4. bounce
   5. unsubscribe
   6. spamreport
   7. dropped
2. “execution_gateway” -
   1. Name of execution channels.
   2. Channel names per tenant can be retrieved by this API endpoint - https://developer.optimove.com/reference/get_actions-getexecutionchannels

Versioning

Version: 1.0