# whatsapp.message.received: a customer sent a WhatsApp message (/api-reference/webhooks/onWhatsappMessageReceived)

## Webhook whatsappMessageReceived

Operation ID: `onWhatsappMessageReceived`
whatsapp.message.received: a customer sent a WhatsApp message
Sent to webhook endpoints subscribed to this event (or to every event).

### Parameters

| Name | In | Required | Description |
|---|---|---|---|
| `webhook-id` | header | no | The event id (`evt_…`). Same on every retry and redelivery: use it to drop duplicates. Webhook endpoints only. |
| `webhook-timestamp` | header | no | When this attempt was sent, Unix seconds. Webhook endpoints only. |
| `webhook-signature` | header | no | Space-separated `v1,<base64 signature>` values (two for 24 hours after a secret rotation). Webhook endpoints only. |
| `X-Webhook-Id` | header | no | Same on every retry of this delivery (the event id for webhook endpoints). |
| `X-Webhook-Event` | header | no | The event type, for example `call.completed`. |
| `X-Signature-SHA256` | header | no | Hex HMAC-SHA256 of the raw request body only. On webhook endpoints it is a compatibility header, keyed with the whole `whsec_...` string: it covers neither `webhook-id` nor `webhook-timestamp`, so a captured request can be replayed. Verify `webhook-signature` and reject a `webhook-timestamp` more than 5 minutes from your clock instead. On a campaign or agent webhook URL it is the only signature, keyed with that URL's secret (when one is set); the signed body carries `timestamp`, so reject one more than 5 minutes old. |

### Request body

`application/json` (required)

```json
{
  "properties": {
    "apiVersion": {
      "const": "v1",
      "type": "string"
    },
    "createdAt": {
      "description": "When the event happened, ISO 8601 UTC.",
      "format": "date-time",
      "type": "string"
    },
    "data": {
      "properties": {
        "contact": {
          "properties": {
            "bsuid": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "id": {
              "format": "uuid",
              "type": "string"
            },
            "leadId": {
              "anyOf": [
                {
                  "format": "uuid",
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "name": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "optInStatus": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "phone": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "tags": {
              "items": {
                "type": "string"
              },
              "type": "array"
            },
            "username": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            }
          },
          "type": "object"
        },
        "conversationId": {
          "format": "uuid",
          "type": "string"
        },
        "entrySource": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "message": {
          "properties": {
            "createdAt": {
              "anyOf": [
                {
                  "description": "ISO 8601 timestamp, UTC.",
                  "format": "date-time",
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "hasMedia": {
              "type": "boolean"
            },
            "id": {
              "format": "uuid",
              "type": "string"
            },
            "mediaFilename": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "mediaMime": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "payload": {
              "additionalProperties": true,
              "description": "The message content as WhatsApp sent it (keys unchanged).",
              "properties": {},
              "type": "object"
            },
            "replyToWamid": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "text": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "type": {
              "description": "`text`, `image`, `button`, `interactive` and so on.",
              "type": "string"
            },
            "wamid": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            }
          },
          "type": "object"
        },
        "phoneId": {
          "format": "uuid",
          "type": "string"
        },
        "serviceWindowExpiresAt": {
          "anyOf": [
            {
              "description": "ISO 8601 timestamp, UTC.",
              "format": "date-time",
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "windowOpen": {
          "description": "True while you can send free-form replies.",
          "type": "boolean"
        }
      },
      "required": [
        "conversationId",
        "message"
      ],
      "type": "object"
    },
    "id": {
      "description": "Event id, `evt_` and 32 hex characters. Same on retries and redeliveries.",
      "type": "string"
    },
    "type": {
      "const": "whatsapp.message.received",
      "type": "string"
    }
  },
  "required": [
    "id",
    "type",
    "apiVersion",
    "createdAt",
    "data"
  ],
  "type": "object"
}
```

### Responses

#### 2XX Received. Anything else is retried.
