Web Hooks

Quickstart

Updated on November 14, 2022

To start receiving events from Crisp websites subscribed to your integration (or just your website if you are using Website Hooks), you must setup an endpoint capable of receiving Web Hooks and responding to them accordingly.

This guide walks you through configuring your Web Hook endpoint, and receiving your first events.

What Is a Web Hook?

Web Hooks are JSON-formatted events sent to your server (via HTTP POST requests) whenever something happens on Crisp, eg. a message was received.

They come handy as whenever something happens on Crisp, we will ring you. That way, you do not have to periodically poll the REST API, eg. poll for new messages.

For example, whenever a message is sent by a visitor on your Crisp website (message:send event namespace), you will receive such a Web Hook:

{
  "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825",
  "event": "message:send",

  "data": {
    "website_id": "42286ab3-b29a-4fde-8538-da0ae501d825",
    "session_id": "session_36ba3566-9651-4790-afc8-ffedbccc317f",
    "type": "text",
    "content": "Hey :)",
    "from": "user",
    "origin": "chat",
    "stamped": true,
    "timestamp": 1506985696616,
    "fingerprint": 150698569649423,

    "user": {
      "nickname": "visitor493603",
      "user_id": "session_36ba3566-9651-4790-afc8-ffedbccc317f"
    }
  },

  "timestamp": 1506985696616
}

You may already know about the RTM API. The data sent to your server from Web Hooks is exactly the same you would receive if connected to the RTM API. Those two systems can be used interchangeably to receive real-time events.

Receiving Web Hooks

Web Hooks can either be received for a single Crisp website (ie. your own website), or multiple Crisp websites (that installed your plugin).

Web Hooks are therefore split into two kinds:

Plugin Hooks: use those when building an integration on the Crisp Marketplace that multiple websites may install. Meaning you will receive events for multiple websites. This is the recommended way for most use cases.
Website Hooks: use those when you wish to receive events for your own private use for a single Crisp website. You will receive events for your own website only. This is the simplest way (although note that it is also more limited).

Working With Web Hooks

Available event namespaces

Each Web Hook type allows you to receive certain real-time events. All available events are listed in a support matrix on the Web Hooks Reference.

As a rule of thumb, consider the following:

Plugin Hooks support the most event namespaces, although you may need manual approval from the Crisp team to receive certain of them.
Website Hooks support the least event namespaces, with the benefit that you do not need any kind of approval.

If in doubt, always use Plugin Hooks. They are the most reliable and secure way to receive Web Hooks, as we will retry any failed delivery. Payloads are also cryptographically signed, so that you can authenticate each Web Hook coming to you.

Common Questions

Help me choose between the RTM API and Web Hooks

Note that a Crisp RTM API is available, which may be preferred over Web Hooks in some rare cases, eg. if you intend to receive a lot of events in short periods of time.

The RTM API runs over WebSocket, thus it is a bit harder to use, but may be more efficient depending on your use case. Check out our RTM reference for more details on how to use the RTM API.

Web Hooks, especially the Plugin Hooks, can be used as a reliable substitute to the RTM API in most use cases.