Webhooks

Webhooks let your backend react to post and account events instead of polling the API.

Manage endpoints

GET/POST /webhooks   { "url": "https://customer.example/webhook", "events": ["post.published"] }
DELETE /webhooks/{id}
POST /webhooks/{id}/test

Event types

post.scheduled, post.awaiting_approval, post.approved, post.rejected, post.publishing, post.published, post.failed, account.connected, account.disconnected, account.needs_reconnect, comment.created.

Payload and signature

POST https://customer.example/webhook
IMMA-Signature: t=1759058400,v1=5f2b...
IMMA-Event-Id: evt_01J...

{
  "type": "post.published",
  "created_at": "...",
  "data": {
    "post_id": "post_...",
    "target_id": "tgt_2",
    "platform": "tiktok",
    "permalink": "https://www.tiktok.com/@dapursekar/video/...",
    "published_at": "..."
  }
}

IMMA-Signature is HMAC-SHA256 of the string t.body (the timestamp, a literal period, then the raw request body), computed with your endpoint's secret. Recompute it on your side and compare before trusting the payload; reject anything where the timestamp is too far in the past to guard against replay.

A post.failed event carries the same error shape described in Errors, including retryable, so you can decide whether to surface it to a user as final or as "trying again".

Retries and deduplication

IMMA AI retries a failing webhook delivery up to 8 times over 24 hours with exponential backoff. Because of this, the same event can arrive more than once: always deduplicate using IMMA-Event-Id, never assume exactly-once delivery.

Testing

POST /webhooks/{id}/test sends a synthetic event to your endpoint so you can verify signature handling before going live.