Webhooks
Get a signed HTTPS request the moment something changes in a workspace.
2 min read
Webhooks push events to your server as they happen: a campaign is created or changes status, a cluster gains posts, a new episode appears, a platform’s numbers advance or a connection breaks. Instead of polling every resource, you subscribe once and react.
How it works#
- You register an HTTPS endpoint and choose which event types it receives.
- When something changes, Listener records an event and sends it to every matching endpoint as a
POSTwith a JSON body. - Each request is signed with your endpoint’s secret. You verify the signature, return
2xxquickly, and do the work. - If your endpoint fails, Listener retries with backoff for three days.
POST /webhooks/listener HTTP/1.1
Host: example.com
Content-Type: application/json
User-Agent: Listener-Webhooks/1.0 (+https://developers.listener.com/docs/webhooks)
Listener-Signature: t=1792056600,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
Listener-Event-Id: evt_1Nf8sKq2LmP0
Listener-Event-Type: campaign.status_changed
Listener-Webhook-Id: we_5Rk2LqP9xT1m
Listener-Delivery-Id: wd_8Hq1Zt0mPx4c
{
"object": "event",
"id": "evt_1Nf8sKq2LmP0",
"type": "campaign.status_changed",
"api_version": "2026-10-14",
"created": "2026-10-14T09:30:00Z",
"workspace_id": "nW7aQ2kL…",
"source": "app",
"data": {
"object": { "object": "campaign", "id": "cmpA7Hq2LmX9vRt4BzKe", "status": "active" },
"previous_attributes": { "status": "upcoming" }
},
"request": null
}Where events come from#
Every event has a source:
source | Meaning | Latency |
|---|---|---|
api | A write made through the API, by you or another integration. request holds its request id and idempotency key. | Seconds |
app | A change someone made in the Listener apps, or new data arriving from a platform. Listener detects these by comparing each workspace’s state every five minutes. | Up to about 5 minutes |
system | Background jobs, such as an AI cluster build finishing. | Seconds |
App-side detection starts when a workspace has its first enabled endpoint, and only watches the kinds of events some endpoint subscribes to. The first pass records a baseline and sends nothing, so you do not receive a flood of “created” events for existing data. These events carry a compact object (the fields used to detect the change, never computed analytics); fetch the full resource from the API when you need it.