On this page

Webhooks

Webhooks make it easy to extend ChatShipper. They offer a way to quickly find out about changes that happen within ChatShipper. You can subscribe to events of interest, and we'll post data to the URL you specify when one of those events occurs.

Also called a web callback or HTTP push API, Webhooks are often used to enable bot interactions, send push notifications or emails based on conversation activity, or create reports or metrics.

Real-time updates are:

  • Sent with a POST request
  • Data is serialized to JSON

Webhook Payload

A Webhook payload has the following possible attributes:

  • id: 774ae370-02cc-11e7-ac41-c38ce8763025 (string) - The unique ID of the Webhook.
  • event: message.create.contact.form (string) - Event that triggered the webhook.
  • timestamp: 2017-03-07T00:24:45.607Z (string) - ISO8601 date and time of when the webhook post was sent.
  • organization: 5c138790ec944f05ff5f6d77 (string) - Organization owning the resource object.
  • activity: (object) - Activity Stream object.
  • data: (object) - Webhook payload.
  • timestamp: 2018-12-20T01:46:56.003Z (string) - Timestamp of the event.

The data property contains one or more resources related to the event. Additionally, the data.links object containing API URLs to primary resources (organization, conversation, message, contact and user) if relevant to the event.

An example of a webhook payload for a chat message in a contact conversation looks like this:

        {
            "id": "774ae370-02cc-11e7-ac41-c38ce8763025",
            "timestamp": "2018-12-19T19:09:01Z",
            "event": "message.create.contact.chat",
            "organization": "5c138790ec944f05ff5f6d77",
            "activity": {
                "@context": "https://www.w3.org/ns/activitystreams",
                "type": "Create",
                "actor": {
                    "id": "https://api.chatshipper.com/v2/users/5c1a99e410419f5fb88cb5f2",
                    "type": "Person"
                },
                "object": {
                    "id": "https://api.chatshipper.com/v2/messages/5c1a974dabcdb128d0e90e93",
                    "type": "Object"
                },
                "published": "2018-12-19T19:09:01Z",
                "summary": "User Jenny Jones created a chat message"
            },
            "data": {
                "conversation": { ...conversation object...},
                "message": { ...message object... },
                "links": { ...links to resources ... }
            }
        }