Webhooks API

The Webhooks API lets you configure and manage webhooks to receive real-time event notifications from DMLY (incoming/outgoing messages, contact updates, tag changes, and more).

Base URL

https://api.dmly.io/api

Authentication

All endpoints require the x-api-key header:

x-api-key: YOUR_API_KEY

Endpoints

List Webhooks

GET /v1/webhooks

Retrieve a list of webhooks.

Response: 200 OK — Array of Webhook

Query Parameters

Example Request

curl -X GET "https://api.dmly.io/api/v1/webhooks?page=1&limit=20" \
  -H "x-api-key: YOUR_API_KEY"

✅ Example Response

[
  {
    "id": "wh_001",
    "name": "My Webhook",
    "serverUrl": "https://example.com/webhook",
    "active": true,
    "events": [
      "incoming_whatsapp_message",
      "outgoing_whatsapp_message",
      "contact_created"
    ],
    "createdAt": "2026-02-20T10:00:00.000Z",
    "updatedAt": "2026-02-20T10:00:00.000Z"
  }
]

2️⃣ Create a Webhook

POST /v1/webhooks

Create a new webhook.

Request Body: Webhook (application/json)
Response: 200 OK — Webhook

Example Request

curl -X POST "https://api.dmly.io/api/v1/webhooks" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
        "name": "My Webhook",
        "serverUrl": "https://example.com/webhook",
        "active": true,
        "events": [
          "incoming_whatsapp_message",
          "outgoing_whatsapp_message",
          "contact_created"
        ]
      }'

✅ Example Response

{
  "id": "wh_001",
  "name": "My Webhook",
  "serverUrl": "https://example.com/webhook",
  "active": true,
  "events": [
    "incoming_whatsapp_message",
    "outgoing_whatsapp_message",
    "contact_created"
  ],
  "createdAt": "2026-02-20T10:00:00.000Z",
  "updatedAt": "2026-02-20T10:00:00.000Z"
}

3️⃣ Update a Webhook

PUT /v1/webhooks/{webhookId}

Update an existing webhook by its unique ID.

Request Body: Webhook (application/json)
Response: 200 OK — Webhook

Path Parameters

Example Request

curl -X PUT "https://api.dmly.io/api/v1/webhooks/wh_001" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
        "name": "My Webhook (Updated)",
        "serverUrl": "https://example.com/webhook",
        "active": true,
        "events": [
          "incoming_whatsapp_message",
          "contact_tag_added"
        ]
      }'

✅ Example Response

{
  "id": "wh_001",
  "name": "My Webhook (Updated)",
  "serverUrl": "https://example.com/webhook",
  "active": true,
  "events": [
    "incoming_whatsapp_message",
    "contact_tag_added"
  ],
  "createdAt": "2026-02-20T10:00:00.000Z",
  "updatedAt": "2026-02-20T10:20:00.000Z"
}

4️⃣ Delete a Webhook

DELETE /v1/webhooks/{webhookId}

Delete a webhook by its unique ID.

Response: 200 OK — DeleteResponse

Path Parameters

Example Request

curl -X DELETE "https://api.dmly.io/api/v1/webhooks/wh_001" \
  -H "x-api-key: YOUR_API_KEY"

✅ Example Response

{
  "success": true
}

📦 Schemas

Webhook Schema

{
  "id": "string",
  "name": "string",
  "serverUrl": "string",
  "active": true,
  "events": [
    "incoming_whatsapp_message",
    "outgoing_whatsapp_message",
    "incoming_instagram_message",
    "outgoing_instagram_message",
    "incoming_telegram_message",
    "outgoing_telegram_message",
    "incoming_messenger_message",
    "outgoing_messenger_message",
    "incoming_website_message",
    "outgoing_website_message",
    "contact_created",
    "contact_tag_added",
    "contact_tag_removed"
  ],
  "createdAt": "string",
  "updatedAt": "string"
}

WebhookResponses Schema

[
  {
    // Webhook object
  }
]

DeleteResponse Schema

{
  "success": true
}

✅ Notes & Best Practices

• Keep webhook endpoints fast and return HTTP 200 quickly.

• Use a queue/worker on your server to process webhook payloads asynchronously.

• Store webhook events in logs for debugging and audit trails.

• Only subscribe to the events you actually need to reduce noise.

• Always use HTTPS endpoints for production webhooks.