Appearance

Event list ​

EventFires when
upload.completedAll channels succeeded
upload.failedAll channels failed
upload.partial_failureSome channels succeeded, some failed
platform.successA specific platform succeeded
platform.failedA specific platform failed

Payload shape ​

All events share a common envelope:

json
{
  "event": "upload.completed",
  "payload": { "...": "event-specific data" },
  "timestamp": "2026-05-13T23:03:06.267Z",
  "deliveryId": "6d0a8f2e..."
}
FieldContent
eventEvent name
payloadEvent-specific data (see below)
timestampDelivery creation time — identical across retries, usable for replay windows
deliveryIdUnique delivery attempt ID — usable for dedup

The same information rides on headers: X-Webhook-Event and X-Webhook-Delivery. See Verifying signatures.

upload.completed / upload.failed / upload.partial_failure ​

Fires once per post when publishing finishes. The payload includes a summary and every channel:

json
{
  "event": "upload.completed",
  "payload": {
    "uploadId": "6a05032a84584482ace13d5f",
    "type": "photo",
    "status": "completed",
    "summary": { "total": 3, "succeeded": 3, "failed": 0 },
    "channels": [
      {
        "platform": "instagram",
        "targetName": "@mybrand",
        "status": "success",
        "postUrl": "https://instagram.com/p/DEF123/",
        "error": null,
        "publishedAt": "2026-05-13T23:03:06.000Z"
      },
      {
        "platform": "x",
        "targetName": "@myhandle",
        "status": "success",
        "postUrl": "https://x.com/myhandle/status/1789...",
        "error": null,
        "publishedAt": "2026-05-13T23:03:05.000Z"
      }
    ]
  },
  "timestamp": "2026-05-13T23:03:06.267Z",
  "deliveryId": "6d0a8f2e..."
}

upload.partial_failure has the same shape with a mixed channels array; upload.failed has all channels failed.

platform.success ​

Fires per platform as soon as that channel finishes — earlier than the upload-level event when a post fans out slowly:

json
{
  "event": "platform.success",
  "payload": {
    "uploadId": "6a05032a84584482ace13d5f",
    "type": "video",
    "platform": "youtube",
    "status": "success",
    "postUrl": "https://youtube.com/shorts/6zaztTmk3Ck",
    "error": null,
    "note": null
  },
  "timestamp": "2026-09-12T10:04:11.000Z",
  "deliveryId": "6d0a8f31..."
}

platform.failed ​

json
{
  "event": "platform.failed",
  "payload": {
    "uploadId": "6a05032a84584482ace13d5f",
    "type": "photo",
    "platform": "instagram",
    "status": "failed",
    "postUrl": null,
    "error": "Requires instagram_content_publish permission",
    "note": null
  },
  "timestamp": "2026-09-12T10:04:09.000Z",
  "deliveryId": "6d0a8f30..."
}

note carries optional context (e.g. TikTok posts that land in the mobile Inbox as platform-side drafts instead of publishing immediately).

Subscribing to specific events ​

When registering a webhook, list only the events you want:

typescript
await socifyr.webhooks.create({
  url: 'https://myapp.com/webhooks/socifyr',
  events: ['platform.failed'], // narrow subscription
})

Delivery behavior ​

  • Deliveries are POST with a JSON body, signed with X-Webhook-Signature (see Verifying signatures)
  • Failed deliveries are retried up to 5 times with exponential backoff starting at 10s
  • The last 50 delivery attempts are inspectable via socifyr.webhooks.deliveries(webhookId)