Webhooks

Set up webhooks to receive notifications about emails, labels, and other Missive events via HTTP POST.

Missive offers a native Zapier integration that lets you trigger actions on new contacts, new comments, new messages (email, SMS), etc.

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 a URL.

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

How to setup

1

Create a webhook rule

Go to Settings > Rules, create a new rule, and select Webhook as the action.

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.

2

Ensure your endpoint handles requests correctly

• The endpoint must accept POST requests and respond within 15 seconds.
• If you expect to perform work that may take longer than 15 seconds, use a background job solution (for example, see this article on background jobs and queueing).

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

Request format

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

webhook-payload.json

{
  "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"
    },
    "team": {
      "id": "2f618f9e-d3d4-4a01-b7d5-57124ab366b8",
      "name": "Hobbits",
      "organization": "93e5e5d5-11a2-4c9b-80b8-94f3c08068cf"
    },
    "color": null,
    "assignees": [
      {
        "id": "6b52b6b9-9b51-46ad-a4e3-82ef3c45512c",
        "name": "Frodo Baggins",
        "email": "[e-mail]",
        "unassigned": false,
        "closed": false,
        "archived": false,
        "trashed": false,
        "junked": false,
        "assigned": true,
        "flagged": false,
        "snoozed": true
      }
    ],
    "assignee_names": "Frodo Baggins",
    "assignee_emails": "[e-mail]",
    "users": [
      {
        "id": "6b52b6b9-9b51-46ad-a4e3-82ef3c45512c",
        "name": "Frodo Baggins",
        "email": "[e-mail]",
        "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": "[e-mail]"
      }
    ],
    "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": "<[e-mail]>",
    "in_reply_to": [],
    "references": [],
    "from_field": {
      "name": "Samwise Gamgee",
      "address": "[e-mail]"
    },
    "to_fields": [
      {
        "name": null,
        "address": "[e-mail]"
      }
    ],
    "cc_fields": [],
    "bcc_fields": [],
    "reply_to_fields": []
  }
}

Breaking change for WhatsApp

For WhatsApp messages, the id in from_field and to_fields identifies authors and recipients by their Business-Scoped User ID (BSUID), the identifier Meta uses to reference a WhatsApp user within your business, instead of the contact's phone number. For example, the id changes from whatsapp:[phone] to whatsapp:US.13491208655302741918.

If your integration relied on these id values being a phone number for WhatsApp, update it to use the BSUID. The username field holds the contact's WhatsApp username when they have set one, otherwise it falls back to their phone number.

Error handling and retry

If the webhook request returns an error status code or does not return a response within 15 seconds, 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.

To perform work that may take over 15 seconds, use a background job solution. See this article.

Request validation

If a validation secret is defined on your rule action, all webhook request 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, 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. Example in Ruby:

request-signature-example.rb

#
# `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:

secure-compare-example.rb

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

Webhooks FAQ

How can I confirm a rule actually triggered its webhook?

Turn on Show rule webhook events. Go to Settings > Preferences > Appearance and, under Conversation view, toggle Show rule webhook events. Tip: type web in the Settings search bar to jump straight to it.

Once enabled, every time a rule fires a webhook action on a conversation, Missive shows an entry for it directly in the conversation timeline. This is a debugging aid: if your webhook doesn't behave as expected, the entry confirms whether Missive triggered the webhook, so you can tell a rule-side issue apart from a problem on your endpoint.

The setting is a per-user preference, off by default. It only controls visibility, so turning it on or off is fully retro-compatible: it never creates or deletes anything, and you can toggle it at any time.

My rule webhook doesn't work. Did the rule fail to trigger?

Usually not. When a webhook action doesn't produce the expected result, the rule almost always did fire and Missive did send the POST request. The problem is typically on the receiving side: a misconfigured endpoint, a server that isn't responding, or a response that times out. Missive knocks on the right door, but nothing answers.

Enable Show rule webhook events (see above) to confirm the webhook was triggered from Missive's side, then check your endpoint's logs and the Error handling and retry behavior above.

Need more specific answers?

Contact us