Skip to main content

​
Send Webhook Relay Action

Use the Send Webhook action to send MessageDesk events directly to your webhook endpoints. This enables you to integrate MessageDesk with external systems, trigger custom workflows, and build powerful automations.
Developer Settings required: Before using webhooks, you need to configure your webhook endpoint and generate a signing secret in Settings → Developer Settings.

​
Setting Up Webhooks

​
1. Configure your webhook endpoint

Navigate to Settings → Developer Settings to:
  • Add your webhook endpoint URL
  • Generate a signing secret for secure webhook validation
  • Manage your webhook configurations

​
2. Add the Send Webhook action to a Relay

When creating or editing a Relay:
  1. Choose your Trigger (e.g., Message Received)
  2. Add any Conditions to control when the webhook fires
  3. Add the Send Webhook action
  4. Select your configured webhook endpoint
The webhook will fire whenever the Relay conditions are met.
Quick start with templates: When you visit the Relays module, you’ll find pre-built Send Webhook templates to help you get started quickly. These templates include common webhook configurations that you can customize for your needs.

​
Webhook Payloads

All webhook payloads from MessageDesk are delivered as Event objects. Each Event contains the data relevant to the specific trigger.
The event name will match 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"
  }
}

​
Validating Data Integrity

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

​
How signature validation works

The signature is generated using the request body and your API secret:
  1. MessageDesk computes a Base64-encoded HMAC-SHA256 hash of the raw request body using your API secret as the key
  2. This hash is sent in the X-MessageDesk-Signature header
  3. 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';

function validateMessageDeskSignature(headers, body) {
    // Capture the X-MessageDesk-Signature header
    const signature = headers['x-messagedesk-signature'];

    // Compute HMAC SHA256
    const hash = crypto.createHmac('sha256', apiSecret)
                       .update(JSON.stringify(body))
                       .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 Settings
  • Confirm the Relay conditions are being met
Signature validation failing
  • Ensure you’re using the correct API secret from Developer Settings
  • 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