Webhooks

MessageDesk supports webhooks in both directions. Use the Send Webhook action to send event data out of MessageDesk to your endpoint when a Relay fires. Use the Inbound Webhook Received trigger to send data into MessageDesk from an outside system and start a Relay.

Outbound webhooks

The Send Webhook action pushes MessageDesk events to an endpoint you control.

Plan required: Outbound webhooks are available on the Pro and Enterprise plans, and they run as a Relay action, so they follow the same plan requirement as Relays. See Pricing.

Developer Tools required: Before you use webhooks, configure your webhook endpoint and generate a signing secret in Settings → Developer Tools. The Developer feature permission gates this configuration. Managers and Operators need Editor or Owner on Developer to add an endpoint or rotate the signing secret. See Team Management.

Setting up webhooks

1. Configure your webhook endpoint

Navigate to Settings → Developer Tools to:

Add your webhook endpoint URL (must be HTTPS and reachable from the public internet)
Generate a signing secret for secure webhook validation
Rotate the signing secret when needed

2. Add the Send Webhook action to a Relay

When creating or editing a Relay:

Choose your Trigger (e.g., Message Received)
Add any Conditions to control when the webhook fires
Add the Send Webhook action
Select your configured webhook endpoint

The webhook fires whenever the Relay’s conditions match.

Quick start with templates: The Relays module ships with pre-built Send Webhook templates that cover common webhook configurations. Customize one for your endpoint to skip the manual setup.

Webhook payloads

MessageDesk delivers all webhook payloads as Event objects. Each Event contains the data relevant to the specific trigger.

The event name matches the trigger you configured on your Relay.

Example: MessageReceived event

When a message is received, the webhook payload includes a Message object:

{
  "id": "01KAE88YX393N7SAE200000000",
  "object": "Event",
  "name": "MessageReceived",
  "workspaceId": "01K6N5WEYHS5N0796000000000",
  "createdAt": "2025-11-19T14:28:39.459465Z",
  "dataType": "Message",
  "data": {
    "id": "01KAE88X48BS8D8D2D00000000",
    "object": "Message",
    "workspaceId": "01K6N5WEYHS5N0796000000000",
    "conversationId": "01K6X3R5NNWKJCSZQY00000000",
    "communicationType": "sms",
    "to": [
      "+17025550000"
    ],
    "from": "+17025551111",
    "text": "The quick brown fox jumps over the lazy dog.",
    "media": [
      "https://example.com"
    ],
    "outbound": false,
    "createdAt": "2025-11-19T14:28:39.459465Z"
  }
}

Example: MessageSent event

When a message is sent from your workspace, the webhook payload includes a Message object with outbound: true:

{
  "id": "01KAE88YX393N7SAE200000000",
  "object": "Event",
  "name": "MessageSent",
  "workspaceId": "01K6N5WEYHS5N0796000000000",
  "createdAt": "2026-07-09T20:14:11.459465Z",
  "dataType": "Message",
  "data": {
    "id": "01KAE88X48BS8D8D2D00000000",
    "object": "Message",
    "workspaceId": "01K6N5WEYHS5N0796000000000",
    "conversationId": "01K6X3R5NNWKJCSZQY00000000",
    "communicationType": "sms",
    "to": [
      "+17025551111"
    ],
    "from": "+17025550000",
    "text": "Thanks for reaching out. A teammate will follow up shortly.",
    "media": [],
    "outbound": true,
    "createdAt": "2026-07-09T20:14:11.459465Z"
  }
}

Example: CommentCreated event

When a teammate posts an internal comment on a conversation, the webhook payload includes a Comment object:

{
  "id": "01KAE88YX393N7SAE200000000",
  "object": "Event",
  "name": "CommentCreated",
  "workspaceId": "01K6N5WEYHS5N0796000000000",
  "createdAt": "2026-07-07T18:15:22.459465Z",
  "dataType": "Comment",
  "data": {
    "id": "01KAE88X48BS8D8D2D00000000",
    "object": "Comment",
    "workspaceId": "01K6N5WEYHS5N0796000000000",
    "conversationId": "01K6X3R5NNWKJCSZQY00000000",
    "authorId": "01K6N5WEYHS5N0796111111111",
    "text": "Heads up, this customer needs a callback today.",
    "createdAt": "2026-07-07T18:15:22.459465Z"
  }
}

Validating data integrity

Your webhook URL is publicly accessible, so treat all incoming requests as untrusted. Each webhook request MessageDesk sends includes an X-MessageDesk-Signature header.

How signature validation works

MessageDesk generates the signature from the request body and your API secret:

MessageDesk computes a Base64-encoded HMAC-SHA256 hash of the raw request body using your API secret as the key.
MessageDesk sends this hash in the X-MessageDesk-Signature header.
You compute the same hash on your end and compare it to verify authenticity.

Example validation code

const crypto = require('crypto');
const apiSecret = 'YOUR_API_SECRET';

// `rawBody` MUST be the exact request body bytes/string received on the
// request, not a parsed-and-re-serialized JSON object. Re-serializing can
// reorder keys or change whitespace, which will invalidate the signature.
// In Express, use `express.raw({ type: 'application/json' })` and read
// `req.body` as a Buffer/string. In a raw Node.js handler, concatenate
// the request stream chunks yourself.
function validateMessageDeskSignature(headers, rawBody) {
    // Capture the X-MessageDesk-Signature header
    const signature = headers['x-messagedesk-signature'];

    // Compute HMAC SHA256 over the raw request body
    const hash = crypto.createHmac('sha256', apiSecret)
                       .update(rawBody)
                       .digest('base64');

    return crypto.timingSafeEqual(Buffer.from(hash), Buffer.from(signature));
}

Always validate signatures: Never trust webhook data without verifying the X-MessageDesk-Signature header matches your computed hash.

Use cases

CRM integration: Sync new messages to your CRM automatically
Custom notifications: Send alerts to Slack, Discord, or other platforms
Data warehousing: Stream conversation data to your analytics platform
Workflow automation: Trigger custom business logic based on MessageDesk events
Third-party integrations: Connect MessageDesk to tools that don’t have native integrations

Best practices

Validate all requests: Always verify the X-MessageDesk-Signature header
Handle retries gracefully: Implement idempotency to handle duplicate webhook deliveries
Respond quickly: Return a 2xx status code within 5 seconds to acknowledge receipt
Use HTTPS: Only configure webhook endpoints that use HTTPS
Monitor failures: Set up alerts for webhook delivery failures
Test thoroughly: Use test events to verify your webhook handler before going live

Troubleshooting

Webhook not firing

Verify the Relay is On (not paused)
Check that your webhook endpoint is configured in Developer Tools
Confirm the Relay conditions are being met

Signature validation failing

Ensure you’re using the correct signing secret from Developer Tools
Verify you’re hashing the raw request body (not parsed JSON)
Check that you’re comparing the signature using a timing-safe comparison

Webhook endpoint not receiving requests

Confirm your endpoint is publicly accessible via HTTPS
Check your server logs for incoming requests
Verify your firewall allows incoming connections

Inbound webhooks

An inbound webhook lets an outside system start a Relay. Your tool sends a POST request to a MessageDesk URL, and any Relay that uses the Inbound Webhook Received trigger runs against the contact in that request. This is the reverse of the Send Webhook action above, which sends data out of MessageDesk.

Get your webhook URL and key

Find your inbound webhook details in Settings → Developer Tools:

Inbound Webhook URL: the address your system sends requests to.
API Key: the value that authenticates each request.

Authentication

Send the API Key in a header named X-MD-Signature on every request:

X-MD-Signature: {your API key}

MessageDesk rejects requests without a valid key.

Payload schema

MessageDesk expects a fixed payload shape. There’s no field mapping inside MessageDesk. Shape your request to match this schema before you send it, using an automation platform or your own code.

{
  "text": "string",
  "contact": {
    "firstName": "string",
    "lastName": "string",
    "email": "string",
    "phone": "string",
    "avatarUrl": "string",
    "company": "string",
    "properties": {
      "Custom Property Name": "value"
    }
  }
}

contact.phone is the only required field. It must be a valid 10-digit number in the format +XXXXXXXXXX. MessageDesk uses it to find the contact the Relay’s actions run against. If the number doesn’t match a saved contact, each action’s Auto-Create checkbox controls whether MessageDesk creates one. See Auto-create contacts.

Notes on the fields:

Every field other than contact.phone is optional.
properties is a map. Each key must match the name of a Custom Property that already exists in your workspace, and each value is the value you want to send. For example, for a Custom Property called favorite color:

"properties": {
  "favorite color": "green"
}

Custom Property validation

Payload values arrive as strings. MessageDesk checks each properties value against its Custom Property’s type and accepts it only if it fits. See Custom Fields for the field types.

Text: any value is accepted.
Number: the value must be numeric.
Date: the value must be in a date format.
True/false: the value must be a boolean value.
Dropdown: the value must exactly match one of the property’s defined options. The match is case-sensitive, so values map 1-to-1 without accidental overwrites.

Say Favorite Color is a dropdown with the options Red, Green, and Blue. MessageDesk accepts only those three values, spelled exactly. A value of red or Purple is rejected.

Auto-create contacts

Each action on a Relay that uses the Inbound Webhook Received trigger includes a contact Auto-Create checkbox. The checkbox is set per action, and it only appears when the Relay’s trigger is Inbound Webhook Received.

Checked: if the payload’s contact.phone doesn’t match a saved contact, MessageDesk creates the contact from the payload’s contact fields, then runs that action against it.
Unchecked: MessageDesk doesn’t create a contact. That action only runs when the payload’s phone number matches a saved contact.

Because the checkbox is per action, one Relay can mix behaviors. For example, a Send Message action can create the contact it texts while an Update Contact Property action on the same Relay only touches saved contacts.

Test your webhook before going live

The Relay builder includes a test step for inbound-webhook Relays. Open the Relay, copy the endpoint URL and key, and send a sample request. MessageDesk shows the parsed payload as a browsable list of fields. Each field is validated against the schema, so you can confirm your request is correct before turning the Relay on. You can re-run the test after edits, and a malformed or oversized payload returns a clear error.

Use the payload in conditions and actions

Once a Relay receives a payload, you can reference its fields:

Conditions: use Webhook Payload Field Equals to branch on a value in the payload.
Actions: Send Message, Send Comment, and Update Contact Property can insert a value from the payload (Event Data) instead of a fixed value. See Relay building blocks for how Event Data works.

Update Contact Property supports mapping payload values to non-text Custom Properties. A Text property accepts any value. Other property types accept either a custom value or the matching Custom Property from the webhook payload, and the payload value must pass the type validation above. This lets you pair the Inbound Webhook Received trigger with Update Contact Property to map payload properties 1-to-1 to the corresponding properties in MessageDesk. If an action uses a Custom Property as Event Data and there’s no value for that property, the action exits early without running. See Event Data.

Limits and compliance

MessageDesk limits inbound webhooks to 10,000 requests per day per workspace.
Messaging compliance still applies to any message a webhook triggers. MessageDesk honors opt-outs, and automated messages should include opt-out language such as “Reply STOP to opt out.”

Getting Started

Messaging

Inbox

Contacts

Relays

Integrations

Search

Settings

Migration

Additional resources

Outbound webhooks

Setting up webhooks

1. Configure your webhook endpoint

2. Add the Send Webhook action to a Relay

Webhook payloads

Example: MessageReceived event

Example: MessageSent event

Example: CommentCreated event

Validating data integrity

How signature validation works

Example validation code

Use cases

Best practices

Troubleshooting

Inbound webhooks

Get your webhook URL and key

Authentication

Payload schema

Custom Property validation

Auto-create contacts

Test your webhook before going live

Use the payload in conditions and actions

Limits and compliance

​Outbound webhooks

​Setting up webhooks

​1. Configure your webhook endpoint

​2. Add the Send Webhook action to a Relay

​Webhook payloads

​Example: MessageReceived event

​Example: MessageSent event

​Example: CommentCreated event

​Validating data integrity

​How signature validation works

​Example validation code

​Use cases

​Best practices

​Troubleshooting

​Inbound webhooks

​Get your webhook URL and key

​Authentication

​Payload schema

​Custom Property validation

​Auto-create contacts

​Test your webhook before going live

​Use the payload in conditions and actions

​Limits and compliance

Outbound webhooks

Setting up webhooks

1. Configure your webhook endpoint

2. Add the Send Webhook action to a Relay

Webhook payloads

Example: MessageReceived event

Example: MessageSent event

Example: CommentCreated event

Validating data integrity

How signature validation works

Example validation code

Use cases

Best practices

Troubleshooting

Inbound webhooks

Get your webhook URL and key

Authentication

Payload schema

Custom Property validation

Auto-create contacts

Test your webhook before going live

Use the payload in conditions and actions

Limits and compliance