> ## Documentation Index
> Fetch the complete documentation index at: https://docs.messagedesk.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Send Webhook Relay Action Setup
> Configure the Send Webhook relay action to push MessageDesk SMS events to your endpoints. Setup, payload structure, headers, and retry behavior explained.
# Send Webhook Relay Action
Use the **Send Webhook** action to send MessageDesk events directly to your webhook endpoints. This lets you integrate MessageDesk with external systems, trigger custom workflows, and build custom Relays.
**Developer Tools required:** Before using webhooks, you'll need to configure your webhook endpoint and generate a signing secret in [**Settings → Developer Tools**](/settings/workspace-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](/settings/workspace-settings/team-management).
***
## Setting up webhooks
### 1. Configure your webhook endpoint
Navigate to [**Settings → Developer Tools**](/settings/workspace-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:
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:
```json theme={null}
{
"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`:
```json theme={null} theme={null}
{
"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](/inbox/comments-mentions) on a conversation, the webhook payload includes a `Comment` object:
```json theme={null}
{
"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 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
```javascript theme={null}
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 Tools**](/settings/workspace-settings/developer-tools)
* Confirm the Relay conditions are being met
**Signature validation failing**
* Ensure you're using the correct signing secret from [**Developer Tools**](/settings/workspace-settings/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
***