Webhooks
Webhooks are the production-grade way to know when a post completed or failed — beats polling getStatus every few seconds.
Webhooks are on every paid plan: up to 2 endpoints on Creator, 10 on Team and 25 on Agency. Free can't create them. See limits.
How it works
- You register an HTTPS endpoint with
eventsyou care about - Socifyr POSTs a JSON payload to that endpoint every time a matching event fires
- Your endpoint validates the HMAC signature and reacts
- Socifyr retries failed deliveries up to 5 times with exponential backoff
Quick setup
const hook = await socifyr.webhooks.create({
url: 'https://myapp.com/webhooks/socifyr',
events: ['upload.completed', 'upload.failed', 'upload.partial_failure'],
})
// A signing secret is generated for you — revealed once in hook.secret.
// Store it: listings only show a masked version.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"]
}'You can also add, pause, test and delete webhooks in the dashboard under API & Integrations → Webhooks.
URL rules. The URL must be reachable from the internet. localhost, private networks (10.x, 192.168.x, 172.16–31.x), link-local and cloud metadata addresses are refused with 400, and redirects are not followed, so register the final URL. Self-hosted installs may use private addresses.
Send a test event
Send a signed webhook.test event to check your endpoint and signature verification. It is a single attempt (no retries), works on paused webhooks, and shows up in the delivery log within seconds.
const { deliveryId } = await socifyr.webhooks.test(hook.id)
const [latest] = await socifyr.webhooks.deliveries(hook.id)
console.log(latest.status, latest.statusCode) // 'success', 200socifyr webhooks list
socifyr webhooks test <webhook-id>curl -X POST https://api.socifyr.com/api/webhooks/<webhook-id>/test \
-H "Authorization: Bearer sk_..."The MCP server has list_webhooks and test_webhook tools for the same thing.
Receiving an event
Every delivery is a POST with these headers:
Content-Type: application/json
X-Webhook-Event: upload.completed
X-Webhook-Signature: sha256=<hex_signature>
X-Webhook-Delivery: <delivery_id>And a JSON body. See Events for the payload shape per event.
Retries
Failed deliveries are retried up to 5 times with exponential backoff starting at 10 seconds.
After the final attempt, the delivery is marked failed and you can inspect it via webhooks.deliveries().
A delivery is successful when your endpoint returns any 2xx status within 10 seconds. A 5xx, a timeout or a network error is retried. A 4xx is not retried (fix the endpoint), and neither is a 3xx redirect, because redirects are not followed.
Best practices
- Respond fast. Return
200immediately and process async — anything over 10s times out. - Verify signatures. Don't trust the body without checking the HMAC; see Signatures.
- Idempotency. The same event can arrive multiple times due to retries — use
X-Webhook-Delivery(or the body'sdeliveryId) as a dedup key. - One endpoint, many events. Subscribe one webhook to multiple events; switch on
X-Webhook-Event.
Testing locally
For local development, expose your dev server with a tunnel:
# ngrok
ngrok http 3000
# cloudflared
cloudflared tunnel --url http://localhost:3000Then register the tunneled URL as your webhook endpoint.