Handling Events

When a campaign event occurs, Symphony sends an HTTP POST to every webhook URL
you've registered for that event type. This page describes the delivery format
and the payload for each event. To register and manage webhook URLs, see
Webhooks.

Delivery format

Every event is delivered as a POST with a JSON body and these headers:

Your endpoint should respond with a 2xx status to acknowledge receipt.

Payload shape

All events share the same envelope:

{
  "eventType": "campaign.created",
  "data": { /* the campaign object */ },
  "timestamp": "2026-07-03T18:24:11.482Z"
}

Event types

campaign.processing, campaign.completed, and campaign.failed are
available for registration; delivery for these lifecycle events is being
rolled out. campaign.created and campaign.updated are live.

Example — campaign.created

{
  "eventType": "campaign.created",
  "data": {
    "id": 98765,
    "name": "Summer Single Launch",
    "platform": "meta",
    "status": "SUBMITTED",
    "startDate": "2026-08-01T00:00:00.000Z",
    "endDate": "2026-08-14T00:00:00.000Z",
    "budget": 500
  },
  "timestamp": "2026-07-03T18:24:11.482Z"
}

Example — campaign.updated

{
  "eventType": "campaign.updated",
  "data": {
    "id": 98765,
    "name": "Summer Single Launch",
    "platform": "meta",
    "status": "ACTIVE",
    "budget": 750
  },
  "timestamp": "2026-07-04T09:10:00.000Z"
}

Verifying and responding

• Match the X-Symphony-Event header (or eventType) to route the event in your handler.
• Return a 2xx quickly; do heavy processing asynchronously so deliveries don't time out.
• A webhook that repeatedly fails delivery is marked failed — confirm your endpoint is publicly reachable and returns 2xx.