Webhooks

A webhook is an HTTP POST request made to an endpoint of your choosing to notify you of some event.

Configuration

To configure a webhook for your instance:

  • Navigate to the Settings tab on the dashboard and click the Add a webhook button.
  • Select the events on which you would like to trigger a request, and point the target URL to somewhere you control.
  • Set your server up to receive POST requests on your target URL.

You can configure as many webhooks as you want. Each optionally targetting different endpoints.

Configuration Options

  • Secret – Used to compute the request signature which we attach to every request we send. You should use this to verify the integrity and authenticity of the request. See Verification.
  • Custom data – Any custom data you provide will be included in the body of every webhook request under the key custom_data.

Request Format

Headers

KeyValue
user-agentalways pusher-webhooks
content-typealways application/json
webhook-event-typethe type of event that triggered the webhook, see below
webhook-id-uuidthe ID of the configured webhook that led to this request
webhook-request-id-uuida UUID representing the specific request, this will stay the same if the webhook is retried
webhook-signaturea hex encoded HMAC of the request body computed with the webhook secret as the key

Body

The request body will always take the following form. For complete examples of each possible event type, see Supported Events.

{
  payload: object,      // the event specific payload
  metadata: {
    created_at: string, // request creation time
    event_type: string, // the event which the request describes
    event_id:   string, // an ID unique to this request (to detect retries)
    product:    string  // the Pusher product the event relates to
  },
  custom_data: object   // the custom data configured in your dashboard
}

Expected Response

We expect your server to respond to webhook requests with a 2XX status code within one second. Non-2XX responses, or responses that take more than one second, will be considered failures.

Retry Strategy

If your server fails to reply with the expected response, we will retry the webhook request up to four times – first after 10 seconds, then a further 30 seconds, a further 120 seconds, and finally a further 300 seconds.

If after four retries (five attempts total) we still don’t receive the expected response your webhook will be marked inactive and no further requests will be attempted until it is marked active again. A webhook can be marked active in the dashboard.

Verification

When you register a new webhook you provide a secret. Each time we send a webhook request to your server, we compute an HMAC (SHA-1) derived from the message body of the webhook request and the webhook’s secret. A hex digest is included as a header with the webhook request. To verify the integrity and authenticity of the webhook request, compute the same HMAC based on your secret and compare it to the one received in the request header.

For example, if your server is written in node and express, you would do something like the following to verify requests before processing them.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
const app = require("express")()
const bodyParser = require("body-parser")
const crypto = require("crypto")

const secret = process.env.CHATKIT_WEBHOOK_SECRET

function verify(req) {
  const signature = crypto
    .createHmac("sha1", secret)
    .update(req.body)
    .digest("hex")

  return signature === req.get("webhook-signature")
}

app.use(
  bodyParser.text({
    // Treat body as raw text regardless of content-type
    type: () => true,
  }),
)

app.post("/chatkit-webhooks", (req, res) => {
  if (verify(req)) {
    console.log("Got a request with body", req.body)
    res.sendStatus(200)
  } else {
    console.log("Got an unverified request; ignoring.")
    res.sendStatus(401)
  }
})

app.listen(5000, () => console.log("listening on :5000"))
Note in particular that we’re treating the request body as plain text here for the purposes of generating the signature.

Supported Events

The currently supported events, each with an example payload, are as follows.

Users Created

Triggered when new users are created. Has body of the form:

{
  "payload": {
    "users": [
      {
        "id": "alice",
        "name": "Alice",
        "avatar_url": "https://example.com/avatar.jpg",
        "created_at": "2019-01-23T11:26:28Z",
        "updated_at": "2019-01-23T11:26:28Z",
        "custom_data": {
          "bar": "baz"
        }
      }
    ]
  },
  "metadata": {
    "created_at": "2019-01-23T11:26:28Z",
    "event_type": "v1.users_created",
    "event_id": "94a912a4-ecfc-462e-9ef5-21bc88ff9170",
    "product": "chatkit"
  },
  "custom_data": {
    "foo": 42,
    "bar": "baz"
  }
}

Users Deleted

Triggered when a user is deleted. Has body of the form:

{
  "payload": {
    "user_ids": [
      "alice",
      "bob"
    ]
  },
  "metadata": {
    "created_at": "2019-01-23T11:26:28Z",
    "event_type": "v1.users_deleted",
    "event_id": "94a912a4-ecfc-462e-9ef5-21bc88ff9170",
    "product": "chatkit"
  },
  "custom_data": {
    "foo": 42,
    "bar": "baz"
  }
}

User Left Room

Triggered when a user leaves a room. Has body of the form:

{
  "payload": {
    "room": {
      "id": "26334188",
      "name": "Mushroom",
      "private": false,
      "created_by_id": "alice",
      "created_at": "2019-01-23T11:26:45Z",
      "updated_at": "2019-01-23T11:26:45Z",
      "custom_data": {
        "foo": 42
      }
    },
    "user": {
      "id": "bob",
      "name": "Bob",
      "created_at": "2019-01-23T11:26:32Z",
      "updated_at": "2019-01-23T11:26:32Z"
    }
  },
  "metadata": {
    "created_at": "2019-01-23T11:26:28Z",
    "event_type": "v1.user_left_room",
    "event_id": "94a912a4-ecfc-462e-9ef5-21bc88ff9170",
    "product": "chatkit"
  },
  "custom_data": {
    "foo": 42,
    "bar": "baz"
  }
}

User Joined Room

Triggered when a user joins a room. Has body of the form:

{
  "payload": {
    "room": {
      "id": "26334188",
      "name": "Mushroom",
      "private": false,
      "created_by_id": "alice",
      "created_at": "2019-01-23T11:26:45Z",
      "updated_at": "2019-01-23T11:26:45Z",
      "custom_data": {
        "foo": 42
      }
    },
    "user": {
      "id": "bob",
      "name": "Bob",
      "created_at": "2019-01-23T11:26:32Z",
      "updated_at": "2019-01-23T11:26:32Z"
    }
  },
  "metadata": {
    "created_at": "2019-01-23T11:26:28Z",
    "event_type": "v1.user_joined_room",
    "event_id": "94a912a4-ecfc-462e-9ef5-21bc88ff9170",
    "product": "chatkit"
  },
  "custom_data": {
    "foo": 42,
    "bar": "baz"
  }
}

Messages Created

Triggered when a message is sent. Has body of the form:

{
  "payload": {
    "messages": [
      {
        "id": 6439819,
        "room_id": "26334188",
        "user_id": "alice",
        "created_at": "2019-01-23T11:26:51Z",
        "updated_at": "2019-01-23T11:26:51Z",
        "parts": [
          {
            "content": "hello",
            "type": "text/plain"
          }
        ]
      }
    ]
  },
  "metadata": {
    "created_at": "2019-01-23T11:26:28Z",
    "event_type": "v1.messages_created",
    "event_id": "94a912a4-ecfc-462e-9ef5-21bc88ff9170",
    "product": "chatkit"
  },
  "custom_data": {
    "foo": 42,
    "bar": "baz"
  }
}

Message Deleted

Triggered when a message is deleted. Has body of the form:

{
  "payload": {
    "message_ids": [
      6439819
    ]
  },
  "metadata": {
    "created_at": "2019-01-23T11:26:28Z",
    "event_type": "v1.messages_deleted",
    "event_id": "94a912a4-ecfc-462e-9ef5-21bc88ff9170",
    "product": "chatkit"
  },
  "custom_data": {
    "foo": 42,
    "bar": "baz"
  }
}

Rooms Created

Triggered when new rooms are created. Has body of the form:

{
  "payload": {
    "rooms": [
      {
        "id": "26334188",
        "name": "Mushroom",
        "private": false,
        "created_by_id": "alice",
        "created_at": "2019-01-23T11:26:45Z",
        "updated_at": "2019-01-23T11:26:45Z",
        "custom_data": {
          "foo": 42
        }
      }
    ]
  },
  "metadata": {
    "created_at": "2019-01-23T11:26:28Z",
    "event_type": "v1.rooms_created",
    "event_id": "94a912a4-ecfc-462e-9ef5-21bc88ff9170",
    "product": "chatkit"
  },
  "custom_data": {
    "foo": 42,
    "bar": "baz"
  }
}

Rooms Deleted

Triggered when a room is deleted. Has body of the form:

{
  "payload": {
    "room_ids": [
      "26334188"
    ]
  },
  "metadata": {
    "created_at": "2019-01-23T11:26:28Z",
    "event_type": "v1.rooms_deleted",
    "event_id": "94a912a4-ecfc-462e-9ef5-21bc88ff9170",
    "product": "chatkit"
  },
  "custom_data": {
    "foo": 42,
    "bar": "baz"
  }
}

Users Removed From Room

Triggered when users are removed from a room. Has body of the form:

{
  "payload": {
    "room": {
      "id": "26334188",
      "name": "Mushroom",
      "private": false,
      "created_by_id": "alice",
      "created_at": "2019-01-23T11:26:45Z",
      "updated_at": "2019-01-23T11:26:45Z",
      "custom_data": {
        "foo": 42
      }
    },
    "users": [
      {
        "id": "bob",
        "name": "Bob",
        "created_at": "2019-01-23T11:26:32Z",
        "updated_at": "2019-01-23T11:26:32Z"
      }
    ]
  },
  "metadata": {
    "created_at": "2019-01-23T11:26:28Z",
    "event_type": "v1.users_removed_from_room",
    "event_id": "94a912a4-ecfc-462e-9ef5-21bc88ff9170",
    "product": "chatkit"
  },
  "custom_data": {
    "foo": 42,
    "bar": "baz"
  }
}

Users Added to Room

Triggered when users are added to a room. Has body of the form:

{
  "payload": {
    "room": {
      "id": "26334188",
      "name": "Mushroom",
      "private": false,
      "created_by_id": "alice",
      "created_at": "2019-01-23T11:26:45Z",
      "updated_at": "2019-01-23T11:26:45Z",
      "custom_data": {
        "foo": 42
      }
    },
    "users": [
      {
        "id": "bob",
        "name": "Bob",
        "created_at": "2019-01-23T11:26:32Z",
        "updated_at": "2019-01-23T11:26:32Z"
      }
    ]
  },
  "metadata": {
    "created_at": "2019-01-23T11:26:28Z",
    "event_type": "v1.users_added_to_room",
    "event_id": "94a912a4-ecfc-462e-9ef5-21bc88ff9170",
    "product": "chatkit"
  },
  "custom_data": {
    "foo": 42,
    "bar": "baz"
  }
}

Message Sent to Offline Users (In Private Rooms Only)

Triggered when a message is sent to a private room and at least one of the room members is offline. Has body of the form:

{
  "payload": {
    "privateRoom": {
      "id": "26334188",
      "name": "Mushroom",
      "private": true,
      "created_by_id": "alice",
      "created_at": "2019-01-23T11:26:45Z",
      "updated_at": "2019-01-23T11:26:45Z",
      "custom_data": {
        "foo": 42
      }
    },
    "sender": {
      "id": "alice",
      "name": "Alice",
      "avatar_url": "https://example.com/avatar.jpg",
      "created_at": "2019-01-23T11:26:28Z",
      "updated_at": "2019-01-23T11:26:28Z",
      "custom_data": {
        "bar": "baz"
      }
    },
    "message": {
      "id": 6439819,
      "room_id": "26334188",
      "user_id": "alice",
      "created_at": "2019-01-23T11:26:51Z",
      "updated_at": "2019-01-23T11:26:51Z",
      "parts": [
        {
          "content": "hello",
          "type": "text/plain"
        }
      ]
    },
    "offline_user_ids": [
      "bob"
    ]
  },
  "metadata": {
    "created_at": "2019-01-23T11:26:28Z",
    "event_type": "v1.message_sent_user_offline",
    "event_id": "94a912a4-ecfc-462e-9ef5-21bc88ff9170",
    "product": "chatkit"
  },
  "custom_data": {
    "foo": 42,
    "bar": "baz"
  }
}