Skip to content

Webhooks API ​

A webhook endpoint receives an HTTP POST from Socifyr when a post finishes or a platform result arrives, so you do not need to poll. This page covers the management API. For event payloads see Webhook events, and for checking the signature on deliveries see Verifying signatures.

Webhooks are available on every paid plan: 2 endpoints on Creator, 10 on Team, 25 on Agency. On Free, creating one returns 403 Webhooks are not available on your current plan. Upgrade to Creator to continue. Self-hosted installs skip plan checks. The endpoint cap per workspace is in Limits.

Which webhook endpoints can I call? ​

MethodPathPurposePermission
POST/webhooksRegister an endpointworkspace.edit
GET/webhooksList endpointsapi_key.view
GET/webhooks/:idGet one endpointapi_key.view
PATCH/webhooks/:idUpdate an endpointworkspace.edit
DELETE/webhooks/:idDelete an endpointworkspace.edit
GET/webhooks/:id/deliveriesLast 50 delivery attemptsapi_key.view

These routes are not available to guarded API keys. Use a session token or an unrestricted key. Auth is described in the REST API overview.

How do I register a webhook endpoint? ​

POST /webhooks

FieldTypeRequiredConstraints
urlstringYesValid http or https URL with a top-level domain
eventsstring[]YesNon-empty. Values: upload.completed, upload.failed, upload.partial_failure, platform.success, platform.failed
descriptionstringNoFree text

You cannot supply a signing secret. Socifyr generates one and returns it once. A request that includes a secret field is rejected with 400.

bash
curl -X POST https://api.socifyr.com/api/webhooks \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://myapp.com/webhooks/socifyr",
    "events": ["upload.completed", "upload.failed", "upload.partial_failure"],
    "description": "Notify the content pipeline"
  }'
json
{
  "success": true,
  "data": {
    "id": "6a05300000000000000000cc",
    "url": "https://myapp.com/webhooks/socifyr",
    "secret": "9f2c...full 64-character hex secret, shown once...",
    "events": ["upload.completed", "upload.failed", "upload.partial_failure"],
    "active": true,
    "description": "Notify the content pipeline",
    "createdAt": "2026-11-13T09:00:00.000Z",
    "updatedAt": "2026-11-13T09:00:00.000Z"
  }
}

Save secret now. Later reads return it masked as **** plus its last 8 characters.

StatusCauseFix
400Invalid URL, empty events, or an unknown event nameFix the body.
400Maximum of N webhook endpoints allowed on your planDelete an endpoint first.
403Webhooks are not available on your current plan. Upgrade to Creator to continue. (Free)Upgrade to Creator or higher.

How do I list or read webhook endpoints? ​

GET /webhooks returns an array. GET /webhooks/:id returns one. Each has the fields above with secret masked. GET /webhooks/:id returns 404 Webhook not found for an unknown ID.

How do I update or pause a webhook? ​

PATCH /webhooks/:id. All fields are optional.

FieldTypeConstraints
urlstringValid http or https URL
eventsstring[]Values from the event list
activebooleanfalse pauses deliveries
descriptionstring
bash
curl -X PATCH https://api.socifyr.com/api/webhooks/6a05300000000000000000cc \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "active": false }'

The response is the updated endpoint with the secret masked. DELETE /webhooks/:id returns 204.

How do I see whether my endpoint received events? ​

GET /webhooks/:id/deliveries returns the 50 most recent delivery attempts, newest first.

bash
curl https://api.socifyr.com/api/webhooks/6a05300000000000000000cc/deliveries \
  -H "Authorization: Bearer sk_..."
json
{
  "success": true,
  "data": [
    {
      "id": "6a05310000000000000000dd",
      "event": "upload.completed",
      "status": "success",
      "statusCode": 200,
      "attempts": 1,
      "createdAt": "2026-11-13T09:00:08.000Z"
    }
  ]
}

Fields: id, event, status (pending, success or failed), statusCode (your endpoint's HTTP status), error (when delivery failed), attempts, createdAt. Deliveries are kept for 30 days. Socifyr waits up to 10 seconds for your endpoint to answer.

Frequently asked questions ​

Can I use a webhook on the Free plan? No. Webhooks need a paid plan (Creator and up). Polling GET /content/:id works on every plan.

Can I choose my own signing secret? No. The server generates a 32-byte secret. Rotate by deleting the endpoint and creating a new one.

Which events fire for a partial failure?upload.partial_failure for the post as a whole. platform.success and platform.failed report each channel as it finishes, if you subscribed to them.

Next steps ​