EventCatalog | Events | Webhook Event

Overview

The Webhook Event represents an incoming webhook from external platforms (WhatsApp Business API, Instagram Direct Messages, or Facebook Messenger). This event is published to the Webhook Queue and consumed by the Webhook Processor.

Payload

The payload follows the WebhookPayload schema:

{
  "type": "whatsapp" | "instagram" | "page",
  "data": {
    // Platform-specific webhook data
  }
}

Schema Definition

const WebhookPayloadSchema = z.object({
  type: z.enum(['whatsapp', 'instagram', 'page']),
  data: z.unknown()
});

Platform-Specific Data

WhatsApp Webhook Data

{
  "type": "whatsapp",
  "data": {
    "entry": [
      {
        "changes": [
          {
            "value": {
              "messaging_product": "whatsapp",
              "metadata": {
                "display_phone_number": "string",
                "phone_number_id": "string"
              },
              "messages": [...]
            }
          }
        ]
      }
    ]
  }
}

Instagram Webhook Data

{
  "type": "instagram",
  "data": {
    "entry": [
      {
        "messaging": [...]
      }
    ]
  }
}

Facebook Messenger Webhook Data

{
  "type": "page",
  "data": {
    "entry": [
      {
        "messaging": [...]
      }
    ]
  }
}

Producing the Event

Webhook events are published to the Webhook Queue by the main API handler when webhook endpoints receive POST requests:

import { SQSClient } from './clients/sqs-client';

const sqsClient = new SQSClient();

await sqsClient.sendMessage({
  type: 'whatsapp',
  data: webhookData
}, 'webhook');

Consuming the Event

The event is consumed by the webhookProcessor Lambda function and routed to the appropriate platform handler:

async function processWebhook(
  payload: WebhookPayload,
  appContext: any,
): Promise<void> {
  switch (payload.type) {
    case 'whatsapp':
      await whatsappChatService.handleWebhook(payload.data);
      break;
    case 'instagram':
      await instagramChatService.handleWebhook(payload.data);
      break;
    case 'page':
      await messengerChatService.handleWebhook(payload.data);
      break;
  }
}

Event-driven architecture documentation: Impulsell

Webhook Event

Event representing a webhook from external platforms (WhatsApp, Instagram, Facebook)