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?
| Method | Path | Purpose | Permission |
|---|---|---|---|
POST | /webhooks | Register an endpoint | workspace.edit |
GET | /webhooks | List endpoints | api_key.view |
GET | /webhooks/:id | Get one endpoint | api_key.view |
PATCH | /webhooks/:id | Update an endpoint | workspace.edit |
DELETE | /webhooks/:id | Delete an endpoint | workspace.edit |
GET | /webhooks/:id/deliveries | Last 50 delivery attempts | api_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
| Field | Type | Required | Constraints |
|---|---|---|---|
url | string | Yes | Valid http or https URL with a top-level domain |
events | string[] | Yes | Non-empty. Values: upload.completed, upload.failed, upload.partial_failure, platform.success, platform.failed |
description | string | No | Free 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.
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"
}'{
"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.
| Status | Cause | Fix |
|---|---|---|
| 400 | Invalid URL, empty events, or an unknown event name | Fix the body. |
| 400 | Maximum of N webhook endpoints allowed on your plan | Delete an endpoint first. |
| 403 | Webhooks 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.
| Field | Type | Constraints |
|---|---|---|
url | string | Valid http or https URL |
events | string[] | Values from the event list |
active | boolean | false pauses deliveries |
description | string |
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.
curl https://api.socifyr.com/api/webhooks/6a05300000000000000000cc/deliveries \
-H "Authorization: Bearer sk_..."{
"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.