---
title: "Register your webhook endpoint"
method: PUT
path: "/webhooks"
tags: ["Webhooks"]
---

# Register your webhook endpoint

`PUT /webhooks`

## Request

- Base URL: `https://api.socially.run/v1`
- URL: `https://api.socially.run/v1/webhooks`
- Auth: HTTP bearer

Point socially.run at an https URL and start receiving events there. The answer carries the signing secret ONCE, when it is minted: keep it. Every delivery is signed with it in the `x-socially-signature` header (`t=<unix>,v1=<hmac-sha256 of "<t>.<body>">`), and that signature is how you know a request is really from us. Calling this again updates the URL or the subscription and keeps the same secret unless you ask to rotate it. Saving also re-enables an endpoint we had disabled. Up to 5 attempts for no answer, 5xx, 408, 425 or 429, with gaps of 30, 60, 120 and 240 seconds. A longer Retry-After extends the gap, capped at one hour. Other 4xx and all redirects are final. Free.

## Request body

- object
  - `url` string, uri, required: Where to POST events, e.g. https://api.yourapp.com/hooks/socially.
  - `events` string[]: Which events to receive: job.completed, job.failed. Defaults to all of them.
  - `rotateSecret` boolean: Mint a new signing secret and return it. The old one stops working.

## Response `200`

Register your webhook endpoint

- object
  - `data` unknown, required

## Other responses

- `400`: VALIDATION_ERROR / INVALID_TARGET / SSRF_BLOCKED: the issues, never the values.
- `401`: UNAUTHORIZED / INVALID_TOKEN: the key is missing or wrong.
- `402`: PAYMENT_REQUIRED / PLAN_GATE: clears by upgrading or buying credits, never by waiting.
- `429`: RATE_LIMIT_EXCEEDED / QUOTA_EXCEEDED: Retry-After says when it clears.
- `default`: Any other failure.

---

[API](https://skmtc.dev/socially/apis/socially-run-send-a-profile-link-get-its-public-data-as-json.md) · [All operations](https://skmtc.dev/socially/apis/socially-run-send-a-profile-link-get-its-public-data-as-json/llms.txt) · [OpenAPI document](https://skmtc.dev/socially/apis/socially-run-send-a-profile-link-get-its-public-data-as-json/revisions/5a0b24534b90?raw)