asyncapi: 2.6.0 info: title: WhatsApp Webhooks description: >- WhatsApp Business Platform webhooks deliver real-time notifications for incoming messages, message status updates, template status changes, account updates, phone number quality changes, and security events. All webhook payloads are sent as HTTP POST requests signed with HMAC-SHA256 using the app secret via the X-Hub-Signature-256 header. Your endpoint must respond with HTTP 200 immediately and process events asynchronously. version: '21.0' contact: name: Meta Platform Support url: https://developers.facebook.com/support/ license: name: Meta Platform Terms url: https://www.whatsapp.com/legal/business-terms externalDocs: description: WhatsApp Webhooks Documentation url: https://developers.facebook.com/docs/whatsapp/cloud-api/webhooks servers: webhookEndpoint: url: '{webhookUrl}' protocol: https description: >- Your HTTPS webhook endpoint configured in the Meta App Dashboard. Must respond to GET requests for verification and POST requests for event delivery. variables: webhookUrl: description: Your configured webhook callback URL security: - hmacSignature: [] channels: /webhook: description: >- Receives all WhatsApp Business Platform webhook events. The field property in each change entry determines the event type. publish: operationId: receiveWebhookEvent summary: Receive webhook events description: >- Receives webhook notifications from the WhatsApp Business Platform. Events include incoming messages, message status updates, template status changes, account updates, and security alerts. message: oneOf: - $ref: '#/components/messages/IncomingMessage' - $ref: '#/components/messages/MessageStatus' - $ref: '#/components/messages/TemplateStatusUpdate' - $ref: '#/components/messages/AccountUpdate' - $ref: '#/components/messages/PhoneNumberQualityUpdate' - $ref: '#/components/messages/SecurityEvent' components: securitySchemes: hmacSignature: type: httpApiKey name: X-Hub-Signature-256 in: header description: HMAC-SHA256 signature of the request body using the app secret messages: IncomingMessage: name: Incoming Message title: Incoming Message Notification summary: A user sent a message to your WhatsApp Business number contentType: application/json payload: $ref: '#/components/schemas/WebhookEnvelope' MessageStatus: name: Message Status title: Message Status Update summary: Status update for a sent message (sent, delivered, read, failed) contentType: application/json payload: $ref: '#/components/schemas/WebhookEnvelope' TemplateStatusUpdate: name: Template Status Update title: Message Template Status Change summary: A message template was approved, rejected, or had its status changed contentType: application/json payload: $ref: '#/components/schemas/TemplateStatusWebhook' AccountUpdate: name: Account Update title: Account Policy Update summary: Policy enforcement or account restriction notification contentType: application/json payload: $ref: '#/components/schemas/AccountUpdateWebhook' PhoneNumberQualityUpdate: name: Phone Number Quality title: Phone Number Quality Rating Change summary: Phone number quality rating changed (flagged or unflagged) contentType: application/json payload: $ref: '#/components/schemas/PhoneQualityWebhook' SecurityEvent: name: Security Event title: Security Alert summary: Security-related event such as PIN change contentType: application/json payload: $ref: '#/components/schemas/SecurityWebhook' schemas: WebhookEnvelope: type: object required: - object - entry properties: object: type: string enum: - whatsapp_business_account entry: type: array items: type: object required: - id - changes properties: id: type: string description: WhatsApp Business Account ID changes: type: array items: type: object required: - value - field properties: value: $ref: '#/components/schemas/MessagesValue' field: type: string enum: - messages MessagesValue: type: object required: - messaging_product - metadata properties: messaging_product: type: string enum: - whatsapp metadata: type: object required: - display_phone_number - phone_number_id properties: display_phone_number: type: string phone_number_id: type: string contacts: type: array items: type: object properties: profile: type: object properties: name: type: string wa_id: type: string messages: type: array items: $ref: '#/components/schemas/IncomingMessageObject' statuses: type: array items: $ref: '#/components/schemas/StatusObject' errors: type: array items: $ref: '#/components/schemas/WebhookError' IncomingMessageObject: type: object required: - from - id - timestamp - type properties: from: type: string description: Sender phone number id: type: string description: WhatsApp message ID timestamp: type: string description: Unix timestamp type: type: string enum: - text - image - video - audio - document - sticker - location - contacts - interactive - button - reaction - order context: type: object properties: from: type: string id: type: string text: type: object properties: body: type: string image: type: object properties: id: type: string mime_type: type: string sha256: type: string caption: type: string video: type: object properties: id: type: string mime_type: type: string sha256: type: string caption: type: string audio: type: object properties: id: type: string mime_type: type: string sha256: type: string voice: type: boolean document: type: object properties: id: type: string mime_type: type: string sha256: type: string filename: type: string caption: type: string sticker: type: object properties: id: type: string mime_type: type: string sha256: type: string animated: type: boolean location: type: object properties: latitude: type: number longitude: type: number name: type: string address: type: string url: type: string contacts: type: array items: type: object properties: name: type: object properties: formatted_name: type: string first_name: type: string last_name: type: string phones: type: array items: type: object properties: phone: type: string type: type: string wa_id: type: string interactive: type: object properties: type: type: string enum: - button_reply - list_reply button_reply: type: object properties: id: type: string title: type: string list_reply: type: object properties: id: type: string title: type: string description: type: string button: type: object properties: text: type: string payload: type: string reaction: type: object properties: message_id: type: string emoji: type: string order: type: object properties: catalog_id: type: string product_items: type: array items: type: object properties: product_retailer_id: type: string quantity: type: integer item_price: type: number currency: type: string text: type: string StatusObject: type: object required: - id - status - timestamp - recipient_id properties: id: type: string description: WhatsApp message ID status: type: string enum: - sent - delivered - read - failed timestamp: type: string recipient_id: type: string conversation: type: object properties: id: type: string expiration_timestamp: type: string origin: type: object properties: type: type: string enum: - business_initiated - user_initiated - referral_conversion - utility pricing: type: object properties: billable: type: boolean pricing_model: type: string category: type: string enum: - business_initiated - user_initiated - referral_conversion - authentication - authentication_international - service - utility - marketing errors: type: array items: $ref: '#/components/schemas/WebhookError' WebhookError: type: object properties: code: type: integer title: type: string message: type: string error_data: type: object properties: details: type: string href: type: string format: uri TemplateStatusWebhook: type: object properties: object: type: string entry: type: array items: type: object properties: id: type: string changes: type: array items: type: object properties: value: type: object properties: event: type: string enum: - APPROVED - REJECTED - PENDING_DELETION - DISABLED - PAUSED - IN_APPEAL - REINSTATED message_template_id: type: integer message_template_name: type: string message_template_language: type: string reason: type: string field: type: string enum: - message_template_status_update AccountUpdateWebhook: type: object properties: object: type: string entry: type: array items: type: object properties: id: type: string changes: type: array items: type: object properties: value: type: object properties: phone_number: type: string event: type: string enum: - VERIFIED_ACCOUNT - DISABLED_UPDATE ban_info: type: object properties: waba_ban_state: type: string waba_ban_date: type: string field: type: string enum: - account_update PhoneQualityWebhook: type: object properties: object: type: string entry: type: array items: type: object properties: id: type: string changes: type: array items: type: object properties: value: type: object properties: display_phone_number: type: string event: type: string enum: - FLAGGED - UNFLAGGED current_limit: type: string field: type: string enum: - phone_number_quality_update SecurityWebhook: type: object properties: object: type: string entry: type: array items: type: object properties: id: type: string changes: type: array items: type: object properties: value: type: object properties: phone_number: type: string event: type: string enum: - PIN_CHANGED field: type: string enum: - security