> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corsair.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> WhatsApp incoming webhooks: event paths, payloads, and response data.

The WhatsApp plugin handles incoming webhooks. Point your provider’s subscription URL at your Corsair HTTP handler (see [Overview](/plugins/whatsapp/overview) for setup context and the exact URL shape).

<Info>
  **New to Corsair?** See [webhooks](/concepts/webhooks) and [hooks](/concepts/hooks).
</Info>

## Webhook map

* `messages`
  * `received` (`messages.received`)
  * `statusChanged` (`messages.statusChanged`)

## HTTP handler setup

```ts app/api/webhook/route.ts theme={null}
import { processWebhook } from "corsair";
import { corsair } from "@/server/corsair";

export async function POST(request: Request) {
    const headers = Object.fromEntries(request.headers);
    const body = await request.json();
    const result = await processWebhook(corsair, headers, body);
    return result.response;
}
```

## Events

## Messages

### Received

`messages.received`

Incoming WhatsApp messages from customers

**Payload**

| Name                 | Type       | Required | Description |
| -------------------- | ---------- | -------- | ----------- |
| `businessAccountId`  | `string`   | Yes      | —           |
| `phoneNumberId`      | `string`   | Yes      | —           |
| `displayPhoneNumber` | `string`   | Yes      | —           |
| `contacts`           | `object[]` | Yes      | —           |
| `messages`           | `object[]` | Yes      | —           |

<AccordionGroup>
  <Accordion title="contacts full type">
    ```ts theme={null}
    {
      wa_id: string,
      profile?: {
        name?: string
      }
    }[]
    ```
  </Accordion>

  <Accordion title="messages full type">
    ```ts theme={null}
    {
      id: string,
      from: string,
      timestamp: string,
      type: string,
      context?: {
        from?: string,
        id?: string,
        referred_product?: {
        }
      },
      text?: {
        body: string
      },
      image?: {
        caption?: string
      },
      audio?: {
      },
      document?: {
        caption?: string
      },
      video?: {
        caption?: string
      },
      sticker?: {
      },
      location?: {
      },
      contacts?: {
      }[],
      interactive?: {
        button_reply?: {
          title?: string
        },
        list_reply?: {
          title?: string
        }
      },
      button?: {
        text?: string
      },
      order?: {
      },
      referral?: {
      },
      errors?: {
      }[]
    }[]
    ```
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Response data full type">
    ```ts theme={null}
    {
      businessAccountId: string,
      phoneNumberId: string,
      displayPhoneNumber: string,
      contacts: {
        wa_id: string,
        profile?: {
          name?: string
        }
      }[],
      messages: {
        id: string,
        from: string,
        timestamp: string,
        type: string,
        context?: {
          from?: string,
          id?: string,
          referred_product?: {
          }
        },
        text?: {
          body: string
        },
        image?: {
          caption?: string
        },
        audio?: {
        },
        document?: {
          caption?: string
        },
        video?: {
          caption?: string
        },
        sticker?: {
        },
        location?: {
        },
        contacts?: {
        }[],
        interactive?: {
          button_reply?: {
            title?: string
          },
          list_reply?: {
            title?: string
          }
        },
        button?: {
          text?: string
        },
        order?: {
        },
        referral?: {
        },
        errors?: {
        }[]
      }[]
    }
    ```
  </Accordion>
</AccordionGroup>

**`webhookHooks` example**

```ts theme={null}
whatsapp({
    webhookHooks: {
        messages: {
            received: {
                before(ctx, args) {
                    return { ctx, args };
                },
                after(ctx, response) {
                },
            },
        },
    },
})
```

***

### Status Changed

`messages.statusChanged`

WhatsApp sent, delivered, read, failed, deleted, or error updates

**Payload**

| Name                 | Type       | Required | Description |
| -------------------- | ---------- | -------- | ----------- |
| `businessAccountId`  | `string`   | Yes      | —           |
| `phoneNumberId`      | `string`   | Yes      | —           |
| `displayPhoneNumber` | `string`   | Yes      | —           |
| `statuses`           | `object[]` | Yes      | —           |
| `errors`             | `object[]` | Yes      | —           |

<AccordionGroup>
  <Accordion title="statuses full type">
    ```ts theme={null}
    {
      id: string,
      status: sent | delivered | read | failed | deleted,
      timestamp: string,
      recipient_id?: string,
      conversation?: {
      },
      pricing?: {
      },
      errors?: {
        code?: number,
        title?: string,
        message?: string,
        error_data?: {
          details?: string
        }
      }[]
    }[]
    ```
  </Accordion>

  <Accordion title="errors full type">
    ```ts theme={null}
    {
    }[]
    ```
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Response data full type">
    ```ts theme={null}
    {
      businessAccountId: string,
      phoneNumberId: string,
      displayPhoneNumber: string,
      statuses: {
        id: string,
        status: sent | delivered | read | failed | deleted,
        timestamp: string,
        recipient_id?: string,
        conversation?: {
        },
        pricing?: {
        },
        errors?: {
          code?: number,
          title?: string,
          message?: string,
          error_data?: {
            details?: string
          }
        }[]
      }[],
      errors: {
      }[]
    }
    ```
  </Accordion>
</AccordionGroup>

**`webhookHooks` example**

```ts theme={null}
whatsapp({
    webhookHooks: {
        messages: {
            statusChanged: {
                before(ctx, args) {
                    return { ctx, args };
                },
                after(ctx, response) {
                },
            },
        },
    },
})
```

***