Subscribe to events

Event subscriptions tell Koil which provider content changes to send to your application. Koil delivers one signed event stream, even when the provider uses webhooks, polling, or backfill behind the scenes.

Start here after you have a connectedProfileId from Connect provider accounts.

How it works

1. Create an HTTPS receiver in your backend. It should accept POST requests, verify Koil delivery headers, store or enqueue the event, and return a 2xx response.

2. Create an Event Destination. POST /v1/event-destinations

3. Store the returned destination ID.

4. Check which content types support events for the Connected Profile. GET /v1/connected-profiles/{connectedProfileId}/capabilities

5. Create an Event Subscription. POST /v1/event-subscriptions

6. Store the returned subscription ID and monitor its state, lastSyncedAt, and reauthRequired fields.

7. Receive matching content.* events at your destination.

Destination Example

{
  "type": "webhook",
  "config": {
    "url": "https://example.com/koil/events",
    "signatureMode": "standard_webhooks",
    "customHeaders": {
      "X-Customer-Route": "inbox"
    }
  }
}

Destinations only describe where events are delivered. Subscriptions choose the Connected Profile and content types.

Subscription Example

{
  "connectedProfileId": "cp_123",
  "eventTypes": ["content.*"],
  "contentTypes": [
    "instagram.media.items",
    "instagram.media.comments",
    "instagram.dm.messages"
  ],
  "destinations": ["evt_dest_123"],
  "policy": {
    "cadence": "PT5M",
    "maxCallsPerDay": 10000,
    "backoff": { "strategy": "exponential", "maxDelay": "PT1H" }
  },
  "backfill": {
    "since": "2026-04-01T00:00:00Z",
    "maxItems": 5000
  }
}

Use contentTypes from the Connected Profile capabilities response.

Receiving Deliveries

Every delivery includes these headers:

• Koil-Signature: HMAC SHA-256 over {timestamp}.{body}.
• Koil-Timestamp: signing timestamp.
• Koil-Event-Id: delivery dedupe id.

Verify the signature against the destination secret before trusting the event. Use the raw request body for verification, reject stale timestamps, and store Koil-Event-Id so retries do not create duplicates.

Return 2xx only after the event is durably stored or enqueued. Return a non-2xx response when processing should be retried.

Backfill and replay

Use backfill when you want Koil to fetch bounded provider history and emit matching events: POST /v1/event-subscriptions/{subscriptionId}/backfill

Use replay when Koil already emitted the event and you need it delivered again: POST /v1/event-subscriptions/{subscriptionId}/replay

Backfill can create new content events from provider history. Replay redelivers existing Koil events, so your receiver should continue deduping by Koil-Event-Id.

What to store

Persist the content fields your product needs from the event stream. Koil emits normalized content events, but your application should store the data it needs for inboxes, workflows, and analytics.