Skip to content

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 ​

  1. You register an HTTPS endpoint with events you care about
  2. Socifyr POSTs a JSON payload to that endpoint every time a matching event fires
  3. Your endpoint validates the HMAC signature and reacts
  4. Socifyr retries failed deliveries up to 5 times with exponential backoff

Quick setup ​

typescript
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.
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"]
  }'

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.

typescript
const { deliveryId } = await socifyr.webhooks.test(hook.id)
const [latest] = await socifyr.webhooks.deliveries(hook.id)
console.log(latest.status, latest.statusCode) // 'success', 200
bash
socifyr webhooks list
socifyr webhooks test <webhook-id>
bash
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:

http
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 200 immediately 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's deliveryId) 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:

bash
# ngrok
ngrok http 3000

# cloudflared
cloudflared tunnel --url http://localhost:3000

Then register the tunneled URL as your webhook endpoint.