Webhooks

Download schema

Endpoints for the webhooks of an app. Socket Chief delivers channel, presence and client events to their URL, signed with the app secret like Pusher webhooks.

List webhooks

GET

https://socket.chief.app/api/v1

/apps/{app}/webhooks

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

List the webhooks of an app by URL.

List webhooks › path Parameters

app

string · required

List webhooks › query Parameters

query

string | null · maxLength: 255

Search results by name.

per_page

integer · min: 1 · max: 100

Number of results per page.

Default: 50

page

integer · min: 1

Page number to return.

Default: 1

List webhooks › Responses

Paginated set of Webhook

Webhook[] · required

object · required

GET/apps/{app}/webhooks

curl https://socket.chief.app/api/v1/apps/:app/webhooks \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "data": [
    {
      "id": "01jbqv2k8m4n6p8r0t2v4x6z8a",
      "app_id": "9d8f6a52-3c1e-4b7a-9f2d-5e6c7b8a9d0e",
      "url": "https://example.com/webhooks/pusher",
      "enabled": true,
      "events": [
        "channel_occupied"
      ],
      "headers": {
        "key": "string"
      },
      "query_params": {
        "key": "string"
      },
      "channel_prefixes": [
        "string"
      ],
      "channel_suffixes": [
        "string"
      ],
      "created_at": "created_at",
      "updated_at": "updated_at"
    }
  ],
  "links": {
    "first": "first",
    "last": "last",
    "prev": "prev",
    "next": "next"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "links": [
      {
        "url": "url",
        "label": "label",
        "active": true
      }
    ],
    "path": "path",
    "per_page": 0,
    "to": 1,
    "total": 0
  }
}

json

application/json

Create a webhook

POST

https://socket.chief.app/api/v1

/apps/{app}/webhooks

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

Add a webhook to an app. It only receives deliveries once it has at least one event.

Create a webhook › path Parameters

app

string · required

Create a webhook › Request Body

SaveWebhookRequest

url

string · uri · maxLength: 255 · required

HTTPS URL the webhook is delivered to.

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

events

array | null · unique

Events delivered to the URL. A webhook without events receives nothing.

Enum values:

channel_occupied

channel_vacated

member_added

member_removed

client_event

Example: ["channel_occupied","channel_vacated"]

headers

array | null · maxItems: 50

HTTP headers sent with every delivery, as an object of header names to values.

Example: {"Authorization":"Bearer my-webhook-token"}

query_params

array | null · maxItems: 50

Query parameters added to the URL of every delivery, as an object of names to values.

Example: {"source":"socketchief"}

channel_prefixes

array | null · maxItems: 50 · unique

Only deliver events of channels whose name starts with one of these prefixes. Empty delivers events of every channel.

Example: ["private-orders."]

channel_suffixes

array | null · maxItems: 50 · unique

Only deliver events of channels whose name ends with one of these suffixes. Empty delivers events of every channel.

Example: [".updates"]

Create a webhook › Responses

The webhook was created.

Webhook · required

POST/apps/{app}/webhooks

curl https://socket.chief.app/api/v1/apps/:app/webhooks \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "url": "https://example.com/webhooks/pusher",
  "events": [
    "channel_occupied",
    "channel_vacated"
  ],
  "headers": {
    "Authorization": "Bearer my-webhook-token"
  },
  "query_params": {
    "source": "socketchief"
  },
  "channel_prefixes": [
    "private-orders."
  ],
  "channel_suffixes": [
    ".updates"
  ]
}'

Example Request Body

{
  "url": "https://example.com/webhooks/pusher",
  "events": [
    "channel_occupied",
    "channel_vacated"
  ],
  "headers": {
    "Authorization": "Bearer my-webhook-token"
  },
  "query_params": {
    "source": "socketchief"
  },
  "channel_prefixes": [
    "private-orders."
  ],
  "channel_suffixes": [
    ".updates"
  ]
}

json

Example Responses

{
  "data": {
    "id": "01jbqv2k8m4n6p8r0t2v4x6z8a",
    "app_id": "9d8f6a52-3c1e-4b7a-9f2d-5e6c7b8a9d0e",
    "url": "https://example.com/webhooks/pusher",
    "enabled": true,
    "events": [
      "channel_occupied"
    ],
    "headers": {
      "key": "string"
    },
    "query_params": {
      "key": "string"
    },
    "channel_prefixes": [
      "string"
    ],
    "channel_suffixes": [
      "string"
    ],
    "created_at": "created_at",
    "updated_at": "updated_at"
  }
}

json

application/json

Get a webhook

GET

https://socket.chief.app/api/v1

/apps/{app}/webhooks/{webhook}

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

Get one of the webhooks of an app.

Get a webhook › path Parameters

app

string · required

webhook

string · required

Get a webhook › Responses

Webhook

Webhook · required

Update a webhook

PATCH

https://socket.chief.app/api/v1

/apps/{app}/webhooks/{webhook}

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

Change the URL, events, headers, query parameters or channel filters of a webhook. Fields left out keep their value, a given field replaces the current value entirely: send the complete headers object to change one header. Send null or an empty value to clear a field.

Update a webhook › path Parameters

app

string · required

webhook

string · required

Update a webhook › Request Body

SaveWebhookRequest

url

string · uri · maxLength: 255 · required

HTTPS URL the webhook is delivered to.

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

events

array | null · unique

Events delivered to the URL. A webhook without events receives nothing.

Enum values:

channel_occupied

channel_vacated

member_added

member_removed

client_event

Example: ["channel_occupied","channel_vacated"]

headers

array | null · maxItems: 50

HTTP headers sent with every delivery, as an object of header names to values.

Example: {"Authorization":"Bearer my-webhook-token"}

query_params

array | null · maxItems: 50

Query parameters added to the URL of every delivery, as an object of names to values.

Example: {"source":"socketchief"}

channel_prefixes

array | null · maxItems: 50 · unique

Only deliver events of channels whose name starts with one of these prefixes. Empty delivers events of every channel.

Example: ["private-orders."]

channel_suffixes

array | null · maxItems: 50 · unique

Only deliver events of channels whose name ends with one of these suffixes. Empty delivers events of every channel.

Example: [".updates"]

Update a webhook › Responses

Webhook

Webhook · required

PATCH/apps/{app}/webhooks/{webhook}

curl https://socket.chief.app/api/v1/apps/:app/webhooks/:webhook \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "url": "https://example.com/webhooks/pusher",
  "events": [
    "channel_occupied",
    "channel_vacated"
  ],
  "headers": {
    "Authorization": "Bearer my-webhook-token"
  },
  "query_params": {
    "source": "socketchief"
  },
  "channel_prefixes": [
    "private-orders."
  ],
  "channel_suffixes": [
    ".updates"
  ]
}'

Example Request Body

{
  "url": "https://example.com/webhooks/pusher",
  "events": [
    "channel_occupied",
    "channel_vacated"
  ],
  "headers": {
    "Authorization": "Bearer my-webhook-token"
  },
  "query_params": {
    "source": "socketchief"
  },
  "channel_prefixes": [
    "private-orders."
  ],
  "channel_suffixes": [
    ".updates"
  ]
}

json

Example Responses

{
  "data": {
    "id": "01jbqv2k8m4n6p8r0t2v4x6z8a",
    "app_id": "9d8f6a52-3c1e-4b7a-9f2d-5e6c7b8a9d0e",
    "url": "https://example.com/webhooks/pusher",
    "enabled": true,
    "events": [
      "channel_occupied"
    ],
    "headers": {
      "key": "string"
    },
    "query_params": {
      "key": "string"
    },
    "channel_prefixes": [
      "string"
    ],
    "channel_suffixes": [
      "string"
    ],
    "created_at": "created_at",
    "updated_at": "updated_at"
  }
}

json

application/json

Delete a webhook

DELETE

https://socket.chief.app/api/v1

/apps/{app}/webhooks/{webhook}

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

Delete a webhook of an app, it stops receiving deliveries.

Delete a webhook › path Parameters

app

string · required

webhook

string · required

Delete a webhook › Responses

The webhook was deleted.

string

Apps Usage