Webhooks

Download schema

Manage webhook subscriptions for real-time events (post.scheduled, post.published, post.failed, post.approved, post.rejected). Deliveries are signed with HMAC-SHA256.

List webhooks

GET

https://api.omnisocials.com/v1

/webhooks

List webhooks › Responses

200

List of webhooks

Webhook[]

Create a webhook

POST

https://api.omnisocials.com/v1

/webhooks

Create a webhook › Request Body

url

string · uri · required

HTTPS URL to receive events. Must resolve to a public host; private, loopback, link-local and unresolvable hosts are rejected with validation_error.

Example: https://example.com/webhooks/omnisocials

events

string[] · required

Enum values:

post.scheduled

post.published

post.failed

post.approved

post.rejected

Create a webhook › Responses

Webhook created. The secret is only returned once at creation.

object

message

string

POST/webhooks

curl -X POST "https://api.omnisocials.com/v1/webhooks" \
  -H "Authorization: Bearer $OMNISOCIALS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/omnisocials/webhook",
    "events": ["post.published", "post.failed"]
  }'

Example Request Body

{
  "url": "https://example.com/webhooks/omnisocials",
  "events": [
    "post.scheduled"
  ]
}

json

Example Responses

{
  "data": {
    "id": "74327072-ec54-473c-837f-63b29187ac16",
    "url": "https://example.com/webhooks/omnisocials",
    "events": [
      "post.scheduled"
    ],
    "is_active": true,
    "last_triggered_at": "2026-10-21T09:00:07.000Z",
    "failure_count": 0,
    "last_failure": {
      "at": "2026-10-18T07:42:31.000Z",
      "status": 404,
      "error": "Endpoint responded with HTTP 404",
      "attempts": 4
    },
    "created_at": "2026-09-30T12:00:00.000Z",
    "secret": "159ba257854f3f71a9b363b04367862705c72e3ed4cd746ecc11274f5c88291e"
  },
  "message": "Webhook created. Save the secret - it will only be shown once. Use it to verify webhook signatures."
}

json

application/json

Get a webhook

GET

https://api.omnisocials.com/v1

/webhooks/{id}

Get a webhook › path Parameters

id

string · required

Get a webhook › Responses

Webhook details

Webhook

Delete a webhook

DELETE

https://api.omnisocials.com/v1

/webhooks/{id}

Delete a webhook › path Parameters

id

string · required

Delete a webhook › Responses

Webhook deleted

No data returned

Update a webhook

PATCH

https://api.omnisocials.com/v1

/webhooks/{id}

Update a webhook › path Parameters

id

string · required

Update a webhook › Request Body

url

string · uri

events

string[]

Enum values:

post.scheduled

post.published

post.failed

post.approved

post.rejected

is_active

boolean

Update a webhook › Responses

Webhook updated

Webhook

PATCH/webhooks/{id}

curl -X PATCH "https://api.omnisocials.com/v1/webhooks/4f6c2b1e-8a3d-4c7e-9b2f-1d5e6a7c8b90" \
  -H "Authorization: Bearer $OMNISOCIALS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"is_active": false}'

Example Request Body

{
  "url": "https://example.com/webhooks/omnisocials",
  "events": [
    "post.scheduled"
  ],
  "is_active": true
}

json

Example Responses

{
  "data": {
    "id": "74327072-ec54-473c-837f-63b29187ac16",
    "url": "https://example.com/webhooks/omnisocials",
    "events": [
      "post.scheduled"
    ],
    "is_active": true,
    "last_triggered_at": "2026-10-21T09:00:07.000Z",
    "failure_count": 0,
    "last_failure": {
      "at": "2026-10-18T07:42:31.000Z",
      "status": 404,
      "error": "Endpoint responded with HTTP 404",
      "attempts": 4
    },
    "created_at": "2026-09-30T12:00:00.000Z"
  }
}

json

application/json

Rotate webhook secret

POST

https://api.omnisocials.com/v1

/webhooks/{id}/rotate-secret

Rotate webhook secret › path Parameters

id

string · required

Rotate webhook secret › Responses

New secret generated. Save it now. It is shown only once.

object

message

string

Approvals Locations

Create a webhook

POST

https://api.omnisocials.com/v1

/webhooks

Create a webhook › Request Body

url

string · uri · required

HTTPS URL to receive events. Must resolve to a public host; private, loopback, link-local and unresolvable hosts are rejected with validation_error.

Example: https://example.com/webhooks/omnisocials

events

string[] · required

Enum values:

post.scheduled

post.published

post.failed

post.approved

post.rejected

Create a webhook › Responses

Webhook created. The secret is only returned once at creation.

object

message

string

Update a webhook

PATCH

https://api.omnisocials.com/v1

/webhooks/{id}

Update a webhook › path Parameters

id

string · required

Update a webhook › Request Body

url

string · uri

events

string[]

Enum values:

post.scheduled

post.published

post.failed

post.approved

post.rejected

is_active

boolean

Update a webhook › Responses

Webhook updated

Webhook