Ask your own question.

Someone from our team or the Crisp community will answer publicly.

We will ask your email to let you know when an answer is published.

Thanks! We will let you know when an answer is published.

Tell us why you are not satisfied.

Tell us how we can improve, and what is missing.

We will answer if we need more details, and improve this help section.

Thanks! We will get back to you if we need more information.

How to use Web Hooks?

Web Hooks can be used by developers as a simple way to get a Web Service notified of real-time events occuring on a Crisp website. For instance, you may want to get your backend notified of messages sent by your website visitors, in real-time.

This guide explains how Web Hooks work, and how to setup them. Web Hooks are available to all Crisp users, whether free or paid.

What do Web Hooks do?

Web Hooks can be used to integrate with Crisp, and receive real-time events from Crisp on a custom HTTP endpoint, ie. on your own servers.

This can be used in the following scenarios:

  1. Store received & sent message history in your database
  2. Store user emails right when a visitor sets their email from the chatbox
  3. Do something when a visitor visits your website eg. send a message to this visitor, from your own backend
  4. Etc. (you may come up with other scenarios)

How to setup Web Hooks?

Web Hooks are available from any Crisp plan, including the Free plan.

1. Prepare the receiving endpoint:

To setup Web Hooks, you first need to setup a public HTTP endpoint, handling HTTP POST payloads. The endpoint can listen on any domain name / URL, and can be hosted on your own servers.

To ensure no external user / attacker can post fake Crisp events to your endpoint URL, it is recommended you append a secret key to the endpoint URL, as a GET parameter, eg. https://endpoint.example.com/crisp/hooks?key=SECRET_KEY. Your backend can then check that the provided key parameter matches the configured security key.

For the safety of your data, prefer HTTPS over HTTP. Crisp does not enforce HTTPS usage, but highly recommends it. If you use HTTPS, Crisp performs a strict certificate check, thus ensure your SSL/TLS certificate is valid; otherwise Web Hooks calls will fail.

2. Add your endpoint to Crisp:

Once the endpoint is ready, create the Web Hooks configuration in Crisp:

  1. Go to your website settings on your Crisp Dashboard.
  2. Pick the target website you need to use the Web Hooks feature on
  3. Scroll down, and open Advanced configuration, then select Web Hooks

web hooks 1
Create a new Web Hook

  1. Click on Add a Web Hook
  2. Enter a name for your Web Hook, an endpoint URL (eg. https://endpoint.example.com/crisp/hooks?key=SECRET_KEY as described before)

web hooks 2
Configure your new Web Hook

  1. Pick a list of events you wish to receive on the URL. Select at least 1 event. It is recommended you pick only the desired events (you can edit it later)
  2. Click on Add Hook Target to create the Web Hook. Selected events will now get delivered to the endpoint URL

3. Check your new Web Hook:

Now that your Web Hook is created and running, it's time to confirm it works properly.

When Crisp forwards an event to your Web Hook endpoint, it considers any HTTP 200 to HTTP 299 reply as successful. Other status codes are considered as failed (even redirect statuses).

To make it easy for you to debug if the last call to your Web Hook succeeded or failed, Crisp logs the status of the last call. You can check it out by refreshing your settings and opening the Web Hooks list again (see examples below).

web hooks 3
Your Web Hook was not called yet

web hooks 4
The last call to your Web Hook failed, check your backend or code

Notice that there may be a 1 minute delay after the delivery of your Web Hook to refresh the status of the last call. Thus, if you feel the shown status is wrong, wait a few minutes and check back.

How to handle Web Hooks events?

Web Hooks events come when a real-time event occurs in your Crisp website. Event payloads have the same data format as the RTM API.

Web Hook general format:

A Web Hook HTTP POST body is JSON-encoded, and formatted as such:

{
  website_id : website_id,  // The Website ID the event occured in
  event      : event,       // The event namespace (see list of events below)
  data       : payload,     // The Web Hook payload (format depends on event namespace)
  timestamp  : timestamp    // The UNIX timestamp of the event (in milliseconds)
}

Web Hook example:

For instance, a Web Hook on a visitor text message may come on URL https://endpoint.example.com/crisp/hooks?key=a2sDx_1 with body:

{
  website_id: "",
  event: "message:send",

  data: {
    "website_id": "-JzqEmX56venQuQw4YV8",
    "session_id": "session_2eb17aee-acae-4f20-972b-f69ea5404fdb",
    "type": "text",
    "content": "Hey :)",
    "from": "user",
    "origin": "chat",
    "stamped": true,
    "timestamp": 1506985696616,
    "fingerprint": 150698569649423,
    "user": {
      "nickname": "visitor493603",
      "user_id": "session_2eb17aee-acae-4f20-972b-f69ea5404fdb"
    }
  },

  timestamp: 1506985696616
}

Which events can be handled?

You can find a list of events that can be handled below:

  • message:updated - Message Updated
  • message:send - Message Send
  • message:received - Message Received
  • message:compose:send - Message Compose Send
  • message:compose:receive - Message Compose Receive
  • message:acknowledge:read:send - Message Acknowledge Read Send
  • message:acknowledge:read:received - Message Acknowledge Read Received
  • message:acknowledge:delivered - Message Acknowledge Delivered
  • session:update_availability - Session Update Availability
  • session:set_email - Session Set Email
  • session:set_phone - Session Set Phone
  • session:set_address - Session Set Address
  • session:set_data - Session Set Data
  • session:set_avatar - Session Set Avatar
  • session:set_nickname - Session Set Nickname
  • session:set_state - Session Set State
  • session:set_block - Session Set Block
  • session:set_segments - Session Set Segments
  • session:set_opened - Session Set Opened
  • session:set_closed - Session Set Closed
  • session:set_mentions - Session Set Mention
  • session:removed - Session Removed
  • session:request:initiated - Session Request Initiated
  • session:sync:capabilities - Session Sync Capabilities
  • session:sync:geolocation - Session Sync Geolocation
  • session:sync:system - Session Sync System
  • session:sync:network - Session Sync Network
  • session:sync:timezone - Session Sync Timezone
  • session:sync:locales - Session Sync Locales
  • session:sync:pages - Session Sync Pages
  • session:sync:events - Session Sync Events
  • people:bind:session - People Bind Session
  • people:sync:profile - People Sync Profile
  • campaign:progress - Campaign Progress
  • campaign:dispatched - Campaign Dispatched
  • campaign:running - Campaign Running
  • website:update_visitors_count - Website Update Visitors Count
  • website:update_operators_availability - Website Update Operators Availability
  • website:users:available - Website Users Available

Troubleshoot common issues

If the last call to your Web Hook failed, or if you don't receive Web Hooks events, check the following:

  • Is your SSL/TLS certificate valid? (not expired, and matching the domain name)
  • Do the receiving server reply with a 2xx status code?
  • Do the receiving server reply fast enough? (ie. less than 10 seconds)

Feel free to contact us if you have any question, or if you cannot solve your issue. We'll gladly help you.

Web Hooks versus RTM API

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 harder to use, but may be more efficient depending on your use case. Also, more event namespaces are available over the RTM API (but, less commonly used events). Check out our API reference for more details on how to use the RTM API.

Web Hooks can be used as a simple substitute to the RTM API in most use cases.

Valerian Saliou
Was this article helpful?YesNo
Thanks! 👍
Don’t find what you are looking for?

Ask your own question.

Ask Now