WahideAPI Docs
POST

Webhook Event: message.received

Real-Time Event

JSON payload schema dispatched by Wahide to your destination server whenever an incoming 1-on-1 private WhatsApp message (text, image, or PDF document) is received by your device.

Incoming Direct Chat Event

This event is triggered strictly by 1-on-1 direct customer chats. Group chats, status stories, public channels, and voice call signals are filtered out at the edge to optimize your server resources.

HTTP Endpoint

POSThttps://api-wa.hidessh.com/your-configured-webhook-url

Authentication

This endpoint requires Bearer authentication via your secret API Key.
Header KeyValueRequired
Content-Typeapplication/jsonRequired
X-Wahide-Secretwhsec_live_...Required
X-Wahide-Delivery-ID01JPLAN0000000000000000099Required
X-Wahide-Eventmessage.receivedRequired
X-Wahide-Device-ID01JPLAN0000000000000000001Required
X-Wahide-Timestamp1725845000Required
User-AgentWahide-WhatsApp-Webhook-Engine/2.0Required

Request Parameters

The request body must be formatted as JSON with the following parameters:

ParameterTypeRequiredDescription
event
stringRequired

Event identifier. For incoming messages, value is always 'message.received'.

example: message.received
device_id
stringRequired

Unique WhatsApp device slot ID in Wahide that received the message.

example: 01JPLAN0000000000000000001
timestamp
integerRequired

Unix epoch timestamp in seconds when the event was dispatched by Wahide.

example: 1725845000
data
objectRequired

Structured container object holding message details.

data.message_id
stringRequired

Unique WhatsApp message identifier (WhatsApp Message ID).

example: 3EB0A1B2C3D4E5F6
data.sender
stringRequired

Normalized sender phone number in E.164 format without special characters.

example: 6281234567890
data.sender_jid
stringRequired

Official WhatsApp Jabber ID of the sender (e.g. 6281234567890@s.whatsapp.net).

example: 6281234567890@s.whatsapp.net
data.push_name
stringOptional

WhatsApp profile display name configured by the sender.

example: John Doe
data.text
stringRequired

Text body content or image/document caption sent by the customer.

example: Please check the attached payment proof
data.has_media
booleanRequired

Indicates whether the message includes an attachment (Photo or PDF Document).

example: true
data.media
objectOptional

Decrypted media object stored in Cloudflare R2 (null if no media or rejected).

data.media.type
stringOptional

Media category: 'image' for JPEG/PNG/WebP photos, or 'document' for PDF files.

example: image
data.media.url
stringOptional

Direct public Cloudflare R2 CDN URL to download the attachment ($0 egress fee).

example: https://pub-r2.wahide.com/tmp/whatsapp-media/01JPLAN000/2026/09/01JPLANXYZ123456.jpg
data.media.file_name
stringOptional

Original filename or generated filename with appropriate extension.

example: payment_receipt.jpg
data.media.mime_type
stringOptional

Standard MIME type of the file (e.g. image/jpeg, image/png, application/pdf).

example: image/jpeg
data.media.file_size
integerOptional

Size of the downloaded attachment in bytes (maximum 1 MB).

example: 245120
data.media_error
stringOptional

Diagnostic error code if attachment was skipped ('file_size_exceeded_1mb', 'unsupported_media_type', 'storage_unavailable').

example: file_size_exceeded_1mb
data.timestamp
integerRequired

Unix epoch timestamp when the message was sent by the customer.

example: 1725844998

Code Examples

request.sh
curl -X POST https://api.your-business.com/webhook \
  -H "Content-Type: application/json" \
  -H "X-Wahide-Secret: whsec_live_9f8e7d6c5b4a3210fedcba9876543210" \
  -H "User-Agent: Wahide-WhatsApp-Webhook-Engine/2.0" \
  -d '{
    "event": "message.received",
    "device_id": "01JPLAN0000000000000000001",
    "timestamp": 1725845000,
    "data": {
      "message_id": "3EB0A1B2C3D4E5F6",
      "sender": "6281234567890",
      "sender_jid": "6281234567890@s.whatsapp.net",
      "push_name": "John Doe",
      "text": "Please check the attached payment proof",
      "has_media": true,
      "media": {
        "type": "image",
        "url": "https://pub-r2.wahide.com/tmp/whatsapp-media/01JPLAN000/2026/09/01JPLANXYZ123456.jpg",
        "file_name": "payment_receipt.jpg",
        "mime_type": "image/jpeg",
        "file_size": 245120
      },
      "timestamp": 1725844998
    }
  }'

Response Formats

Mandatory HTTP acknowledgment response required from your server to confirm successful event receipt.

application/json • 200 OK
{\n  "status": "success",\n  "received": true\n}

Response Attributes Breakdown

AttributeTypeDescription
statusstringReceipt acknowledgment status indicator.