@jackiemacklein/nettz-utils
Version:
Serviços de imagem, e-mail, códigos de barras, utilitários numéricos e componentes React para apps Node.js com TypeScript
51 lines (50 loc) • 2.04 kB
TypeScript
/**
* @author Jackiê Macklein
* @company Onside tecnologia/Nettz
* @copyright Todos direitos reservados.
* @description Utilitários para webhooks da WhatsApp Business Platform (Meta).
* Referência: https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/overview
*/
/** Envelope típico do webhook (`object` + `entry`). */
export interface WhatsAppWebhookEnvelope {
object: string;
entry: WhatsAppWebhookEntry[];
}
export interface WhatsAppWebhookEntry {
id: string;
changes: WhatsAppWebhookChange[];
}
export interface WhatsAppWebhookChange {
field: string;
value: WhatsAppWebhookChangeValue;
}
/** Conteúdo de `changes[].value` — campos variam por `field` (ex.: messages). */
export interface WhatsAppWebhookChangeValue {
messaging_product?: string;
metadata?: {
display_phone_number?: string;
phone_number_id?: string;
};
contacts?: unknown[];
messages?: unknown[];
statuses?: unknown[];
errors?: unknown[];
[key: string]: unknown;
}
/**
* Verificação inicial do webhook (GET): Meta envia `hub.mode`, `hub.verify_token`, `hub.challenge`.
* Se o token confere, devolva o `hub.challenge` no corpo da resposta com status 200.
*
* @returns string a ser retornada como texto/resposta, ou `null` se não verificar.
*/
export declare function getWhatsAppWebhookChallenge(query: Record<string, string | string[] | undefined>, expectedVerifyToken: string): string | null;
/**
* Valida o header `X-Hub-Signature-256` do POST (corpo **bruto** UTF-8, sem re-serializar o JSON).
* Usa o **App Secret** do app Meta.
*/
export declare function verifyWhatsAppWebhookSignature(rawBody: string, signatureHeader: string | undefined | null, appSecret: string): boolean;
/**
* Faz `JSON.parse` e valida estrutura mínima `object` + `entry` (array).
* Não valida assinatura; use `verifyWhatsAppWebhookSignature` antes, com o body bruto.
*/
export declare function parseWhatsAppWebhookPayload(rawBody: string): WhatsAppWebhookEnvelope;