Using Product Agents with Webhooks¶

This guide explains how to integrate Product Agents with your own systems using webhooks.

It covers:

• When to use the webhook integration
• How webhook delivery works
• The webhook payload structure
• Delivery guarantees and expectations
• What your system is responsible for handling

This guide is intended for developers and technical teams who want full control over message delivery.

When to use webhooks¶

Use the webhook integration if:

• You are not using Klaviyo
• You want to send Product Agent messages through a custom ESP
• You need to route messages into internal systems
• You want full control over rendering, delivery, and retries

If you want a managed email setup with minimal implementation effort, use the Klaviyo integration instead.

Integration model¶

When using webhooks as the delivery channel:

• Product Agents evaluate triggers and scheduling rules
• A message payload is generated
• The payload is sent as an HTTP request to your endpoint
• Your system is responsible for all downstream handling

Product Agents do not:

• Retry failed webhook deliveries
• Render templates
• Enforce consent or suppression rules

Webhook endpoint requirements¶

Your webhook endpoint must:

• Accept HTTPS POST requests
• Respond with a 2xx status code on successful receipt
• Be able to handle bursts of requests
• Be idempotent

If your endpoint does not return a 2xx response, the delivery is considered failed.

Delivery behavior¶

Webhook delivery is best-effort.

• Each Product Agent message results in one webhook request
• Requests are sent at the scheduled send time
• Failed requests are not retried
• No backoff or retry logic is applied

If delivery reliability is required, your system must implement its own retry and queuing logic.

Webhook payload structure¶

Product Agents send the following JSON payload in the request body.

{
  "event": {
    "id": "string",
    "timestamp": "ISO-8601 string",
    "messageType": "string"
  },
  "customer": {
    "id": "string",
    "email": "string|null"
  },
  "content": {
    "subject": "string",
    "previewText": "string",
    "headline": "string",
    "body": "string",
    "callToAction": "string"
  },
  "primaryProducts": [
    {
      "title": "string",
      "description": "string",
      "image": {
        "scalableUrl": "string",
        "url": "string"
      },
      "url": "string",
      "price": "number|null",
      "oldPrice": "number|null",
      "currency": "string",
      "onSale": "boolean"
    }
  ],
  "otherProducts": [
    {
      "title": "string",
      "description": "string",
      "image": {
        "scalableUrl": "string",
        "url": "string"
      },
      "url": "string",
      "price": "number|null",
      "oldPrice": "number|null",
      "currency": "string",
      "onSale": "boolean"
    }
  ]
}

Payload notes¶

• primaryProducts is always an array and may contain one or more products
• otherProducts may be empty
• All string fields may contain HTML
• All fields should be treated as optional unless required by your implementation
• For information about how the image scaling mechanism works refer to Integration Overview

messageType values¶

The messageType field identifies which Product Agent generated the message.

These values are aligned with the Klaviyo integration and support-facing naming.

Repeatablity and duplication¶

Product Agents may send multiple webhook events over time for the same customer or context.

Your system should:

• Treat webhook requests as non-unique
• Use the event.id field to deduplicate if needed
• Avoid assuming exactly-once delivery