Social API reference

Social API · Webhooks

post/v1/communities/{community_id}/webhooksAuth

Create a community webhook. Multiple subscribers per community are supported (cap 10). Returns the signing secret ONCE — store it. Pass an `Idempotency-Key` header so a retried create replays the SAME secret instead of minting a duplicate subscriber.

Deprecated: use `/v1/communities/{community_id}/webhooks/endpoints` (or `/v1/workspaces/{workspace_id}/webhooks/endpoints` for one endpoint that receives every community's events): Standard Webhooks signing, event descriptions, Send test that reports the result, an event log, replay and rotation with a grace period. Responses carry `Deprecation: true` and `Sunset: Fri, 15 Jan 2027 00:00:00 GMT`.

Path parameters

community_id*string

Social community UUID.

Headers

Idempotency-Keystring

Opaque client-generated string (1–256 chars, `[A-Za-z0-9._:-]`) used to deduplicate retries within a 24h window. The signing secret is returned exactly once; a replay returns the original response (including the secret) with `Idempotent-Replay: true`. Same key + different body returns 409 `IDEMPOTENCY_KEY_REUSE`.

Request body

url*string

Subscriber URL. Must be `https://`.

Example: "https://example.com/webhooks/social"

event_types*array

Event types to subscribe to. Unknown values are rejected with a 400 naming the valid set — see GET /v1/webhook-event-types.

Example: ["post.created","comment.created"]

Response · 201 Webhook created.

id*string · uuid

Webhook UUID.

Example: "dddddddd-0000-0000-0000-000000000001"

community_id*string · uuid

Owning community UUID.

Example: "cccccccc-cccc-cccc-cccc-cccccccccccc"

url*string

Subscriber URL.

Example: "https://example.com/webhooks/social"

event_types*array

Subscribed event types. Each item is one of the social event names — see GET /v1/webhook-event-types for the live catalog.

Example: ["post.created","comment.created"]

signing_secret_hint*string

Last 4 chars of the signing secret. Use the full secret returned by create / rotate to verify the Standard Webhooks `webhook-signature` header (or, until the sunset, the X-Pcft-Signature header).

Example: "abcd"

disabled_at*string · date-time

ISO timestamp when the webhook was auto-disabled (or null if active).

Example: null

disabled_reason*string

Why the webhook is off: `manual` (switched off) or `failing` (switched off automatically after 20 failures in a row or 24 h of failures). Null while it is on.

Example: null

consecutive_failures*number

Consecutive failed attempts since the last success.

Example: 0

last_success_at*string · date-time

ISO timestamp of the most recent 2xx response.

Example: null

last_failure_at*string · date-time

ISO timestamp of the most recent non-2xx response.

Example: null

created_at*string · date-time

ISO timestamp.

Example: "2026-05-01T12:00:00.000Z"

updated_at*string · date-time

ISO timestamp.

Example: "2026-05-01T12:00:00.000Z"

signing_secret*string

Full plaintext HMAC signing secret. Returned ONCE — store it; subsequent reads only expose the last-4 hint.

Example: "abc...xyz"

Example

Request

POST https://social.productcraft.co/v1/communities/{community_id}/webhooks
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "url": "https://example.com/webhooks/social",
  "event_types": [
    "post.created",
    "comment.created"
  ]
}

Response

{
  "id": "dddddddd-0000-0000-0000-000000000001",
  "community_id": "cccccccc-cccc-cccc-cccc-cccccccccccc",
  "url": "https://example.com/webhooks/social",
  "event_types": [
    "post.created",
    "comment.created"
  ],
  "signing_secret_hint": "abcd",
  "disabled_at": null,
  "disabled_reason": null,
  "consecutive_failures": 0,
  "last_success_at": null,
  "last_failure_at": null,
  "created_at": "2026-05-01T12:00:00.000Z",
  "updated_at": "2026-05-01T12:00:00.000Z",
  "signing_secret": "abc...xyz"
}