Webhook events

Every webhook payload shares the same envelope. The data object is event-specific — the shapes are documented below.

Common envelope

{
  "id":        "evt_1abcd23_4ef5",   // unique, use for deduplication
  "type":      "<event.name>",
  "createdAt": "2026-04-22T14:00:00.000Z",
  "data":      { ... }               // event-specific, see below
}

Post events

post.scheduled

Fires when a post is successfully queued for future publishing.

{
  "id":        "evt_2bc_sched",
  "type":      "post.scheduled",
  "createdAt": "2026-04-22T14:00:00.000Z",
  "data": {
    "postId":      "pst_abc123",
    "scheduledAt": "2026-04-23T09:00:00.000Z",
    "platforms":   ["instagram", "twitter"],
    "profileId":   "prof_xyz"
  }
}

post.published

Fires when a post has been successfully published to all target platforms.

{
  "id":        "evt_3cd_pub",
  "type":      "post.published",
  "createdAt": "2026-04-22T14:05:00.000Z",
  "data": {
    "postId":    "pst_abc123",
    "published": 3,
    "failed":    0,
    "total":     3
  }
}

post.failed

Fires when a post failed to publish on all platforms after all retries.

{
  "id":        "evt_4de_fail",
  "type":      "post.failed",
  "createdAt": "2026-04-22T14:06:00.000Z",
  "data": {
    "postId": "pst_abc123",
    "reason": "All platforms rejected the post",
    "platformResults": {
      "instagram": { "ok": false, "error": "Media aspect ratio not supported" },
      "twitter":   { "ok": false, "error": "Duplicate content" }
    }
  }
}

post.partial

Fires when a post published successfully on at least one platform but failed on one or more others. The platformResults object contains per-platform outcome details.

{
  "id":        "evt_5ef_part",
  "type":      "post.partial",
  "createdAt": "2026-04-22T14:06:00.000Z",
  "data": {
    "postId":    "pst_abc123",
    "published": 2,
    "failed":    1,
    "total":     3,
    "platformResults": {
      "instagram": { "ok": true,  "platformPostId": "17854321000123456" },
      "twitter":   { "ok": true,  "platformPostId": "1783499900001234560" },
      "linkedin":  { "ok": false, "error": "Token expired — reconnect your account" }
    }
  }
}

Account events

account.connected

Fires when a social account is successfully connected to a profile.

{
  "id":        "evt_6fg_conn",
  "type":      "account.connected",
  "createdAt": "2026-04-22T14:10:00.000Z",
  "data": {
    "accountId": "acct_111",
    "platform":  "instagram",
    "username":  "myband_official",
    "profileId": "prof_xyz"
  }
}

account.disconnected

Fires when a social account is removed or its token is revoked.

{
  "id":        "evt_7gh_disc",
  "type":      "account.disconnected",
  "createdAt": "2026-04-22T14:12:00.000Z",
  "data": {
    "accountId": "acct_111",
    "platform":  "instagram",
    "reason":    "token_revoked"
  }
}

Team events

team.member_invited

Fires when a new team member invitation is sent.

{
  "id":        "evt_8hi_inv",
  "type":      "team.member_invited",
  "createdAt": "2026-04-22T14:15:00.000Z",
  "data": {
    "inviteId":  "inv_001",
    "email":     "colleague@example.com",
    "role":      "editor",
    "invitedBy": "usr_owner123"
  }
}

team.role_changed

Fires when a team member's role is updated.

{
  "id":        "evt_9ij_role",
  "type":      "team.role_changed",
  "createdAt": "2026-04-22T14:20:00.000Z",
  "data": {
    "userId":   "usr_456",
    "oldRole":  "editor",
    "newRole":  "admin",
    "changedBy": "usr_owner123"
  }
}

Billing events

subscription.upgraded

Fires when a workspace upgrades to a higher plan.

{
  "id":        "evt_10jk_sub",
  "type":      "subscription.upgraded",
  "createdAt": "2026-04-22T14:25:00.000Z",
  "data": {
    "workspaceId": "ws_789",
    "fromPlan":    "starter",
    "toPlan":      "pro",
    "effectiveAt": "2026-04-22T14:25:00.000Z"
  }
}

payment.succeeded

Fires when a subscription payment is successfully collected.

{
  "id":        "evt_11kl_pay",
  "type":      "payment.succeeded",
  "createdAt": "2026-04-22T14:26:00.000Z",
  "data": {
    "workspaceId": "ws_789",
    "amountCents": 2900,
    "currency":    "usd",
    "invoiceId":   "in_1PqR2sXYZ"
  }
}