Guide

API Documentation

Summary

Webhooks

Missive allows applications to be notified of certain actions (incoming emails, outgoing emails, label changes, etc.) in the form of an HTTP POST payload sent to an URL.

Example Creating a new entry in a CRM every time an email is received and meets certain conditions.

How to setup

To subscribe to a webhook you need to create a rule with a webhook action. Open your Missive settings, go to the Rule tab, create a new rule and select Webhook as the action.

Note You need to be the admin or owner of an organization subscribed to the Productive plan in order to create rules.

When saving the rule your endpoint should already be configured to receive a POST request successfully. A validation request will be sent to make sure your endpoint is working.

Request format

Each webhook request contains a JSON object. The JSON object follows this general structure:

{
  "rule": {
    "id": "45408b30-aa3a-45n1-bh67-0a0cb8da9080",
    "description": "Notify elfs",
    "type": "label_change"
  },
  "conversation": {
    "id": "47a57b76-df42-4d8k-927x-80dbe5d87191",
    "subject": "Mordor GPS coordinates",
    "latest_message_subject": "Fwd: Mordor GPS coordinates",
    "organization": {
      "id": "93e5e5d5-11a2-4c9b-80b8-94f3c08068cf",
      "name": "Fellowship"
    },
    "color": null,
    "assignees": [
      {
        "id": "6b52b6b9-9b51-46ad-a4e3-82ef3c45512c",
        "name": "Frodo Baggins",
        "email": "frodo@fellowship.org",
        "unassigned": false,
        "closed": false,
        "archived": false,
        "trashed": false,
        "junked": false,
        "assigned": true,
        "flagged": false,
        "snoozed": true
      }
    ],
    "assignee_names": "Frodo Baggins",
    "assignee_emails": "frodo@fellowship.org",
    "users": [
      {
        "id": "6b52b6b9-9b51-46ad-a4e3-82ef3c45512c",
        "name": "Frodo Baggins",
        "email": "frodo@fellowship.org",
        "unassigned": false,
        "closed": false,
        "archived": false,
        "trashed": false,
        "junked": false,
        "assigned": true,
        "flagged": false,
        "snoozed": true
      }
    ],
    "attachments_count": 0,
    "messages_count": 1,
    "authors": [
      {
        "name": "Samwise Gamgee",
        "address": "sam@fellowship.org"
      }
    ],
    "drafts_count": 0,
    "send_later_messages_count": 0,
    "tasks_count": 0,
    "completed_tasks_count": 0,
    "shared_labels": [
      {
        "id": "146ff5c4-d5la-3b63-b994-76711fn790lq",
        "name": "Elfs"
      }
    ],
    "shared_label_names": "Elfs",
    "app_url": "missive://mail.missiveapp.com/#inbox/conversations/47a57b76-df42-4d8k-927x-80dbe5d87191",
    "web_url": "https://mail.missiveapp.com/#inbox/conversations/47a57b76-df42-4d8k-927x-80dbe5d87191"
  },
  "latest_message": {
    "id": "86ef8bb8-269c-4959-a4f0-213db4e67844",
    "subject": "Fwd: Mordor GPS coordinates",
    "preview": "Hi Mr. Gamgee, I discovered something really disturbing about the Mordor coordinates we had.",
    "type": "email",
    "delivered_at": 1548415828,
    "updated_at": 1548434556,
    "created_at": 1548434555,
    "email_message_id": "\\u002cMx4teIvYRDqVI9osfdRZKA@1.lotrmail.net\\u003e",
    "in_reply_to": [],
    "references": [],
    "from_field": {
      "name": "Samwise Gamgee",
      "address": "sam@fellowship.org"
    },
    "to_fields": [
      {
        "name": null,
        "address": "sam@fellowship.org"
      }
    ],
    "cc_fields": [],
    "bcc_fields": [],
    "reply_to_fields": []
  }
}

Error handling and retry

If the webhook request returns an error status code or times out, the request will be retried up to 5 times over a period of 8 minutes. If a webhook rule fails more than 50 times in a row, the rule will be automatically disabled. You can re-enable it from the Rules settings tab.

Request validation

If a validation secret is defined on your rule action, all webhook requests headers will include a X-Hook-Signature hash signature of the payload. With this signature, you can validate that the request is coming from Missive. To do so, you must compute the signature yourself and compare it to the one provided in the request header.

The signature starts with sha256= followed by a HMAC hexdigest. Here's some sample code showing how to compute the signature in Ruby:

#
# `secret` is the "Signature secret" you set in your Missive rule action
# `request_body` is the full HTTP request body
#
computed_signature = 'sha256=' + OpenSSL::HMAC.hexdigest(
  OpenSSL::Digest.new('sha256'), secret, request_body
)

Make sure to assess equality between the header signature and the one you've computed using a method that prevents timing attacks against regular equality operators. In Ruby, you can use secure_compare.

valid = Rack::Utils.secure_compare(x_hook_signature, computed_signature)


Last updated on September 25, 2019

Need more specific answers?

Contact us via our Help Center