PieSocket Webhooks

Run code on your own server whenever something happens on a PieSocket channel, no polling required.

What you can use webhooks for

• Persisting every message sent through a channel into your own database
• Triggering notifications, emails, or backend workflows in response to activity
• Syncing channel activity into a CRM, analytics tool, or data warehouse
• Reacting to users joining, leaving, or typing in a channel

Setting up a webhook

Webhooks are configured in your dashboard, under PieSocket dashboard → Webhook.

A webhook is a single endpoint per API key. Once set, PieSocket sends a POST request to this URL for every message published on any channel using that key.

1. Open your PieSocket from the dashboard and go to its Webhook tab
2. Select the API key from the dropdown
3. Enter your endpoint URL
4. Click Update

When you save, PieSocket immediately sends a test request to the URL, it must respond with a 2xx status or the save is rejected, so make sure the endpoint is live before configuring it.

Removing a webhook

Go back to the same Webhook tab and click Delete next to the endpoint you want to remove.

Payload format

The shape depends on which protocol version your clients connect with.

V3 clients send one request per message:

{
  "apiKey": "your-api-key",
  "channel": "room-1",
  "message": "Hello world"
}

V4 clients are batched, a single request can carry up to 250 messages (or ~4MB, whichever limit is hit first). If more messages arrive than fit in one request, they're split across multiple requests sent back to back:

{
  "apiKey": "your-api-key",
  "messages": [
    { "channel": "room-1", "message": "Hello world", "timestamp": 1732000000000 },
    { "channel": "room-2", "message": "Another message", "timestamp": 1732000000123 }
  ]
}

Design your endpoint to always accept either shape, this is decided per message by which protocol version published it, not by your cluster as a whole. If some of your clients are on V3 and others have moved to V4, the same webhook URL receives both shapes at once, see the migration guide if that applies to you.

Verifying requests

Webhook requests aren't signed. If you need to confirm a request genuinely came from PieSocket, include a secret token in the URL itself when configuring the endpoint (e.g. https://yourapp.com/hooks/piesocket?token=xxxx) and check it on your side.

Delivery behavior

• Requests are sent as POST with Content-Type: application/json
• Your endpoint has 15 seconds to respond
• Failed or slow deliveries are not retried, treat webhooks as best-effort rather than guaranteed delivery, and design your endpoint to be fast and highly available
• Return a 2xx status as soon as you've accepted the payload, do any heavier processing asynchronously rather than inside the request handler