# GREEN-API Webhooks

GREEN-API is a WhatsApp API gateway. With the **Webhook Endpoint** technology,
the GREEN-API server `POST`s a JSON notification to your `webhookUrl` for every
incoming message, outgoing message status, instance state change, call, and so
on. The notification type is in the body's `typeWebhook` field.

## When to Use This Skill

* How do I receive GREEN-API WhatsApp webhooks?
* How do I verify GREEN-API webhooks / check the `webhookUrlToken`?
* How do I handle `incomingMessageReceived` or `outgoingMessageStatus` notifications?
* Why does my GREEN-API webhook get 401 when I set a Webhook URL Token?
* Why am I receiving the same GREEN-API notification more than once?

## Verification (core)

GREEN-API webhooks have **no signature**: there is no HMAC, no timestamp, and no
Standard Webhooks headers. The only authentication is the optional
**`webhookUrlToken`** instance setting.

> **Caveat:** when `webhookUrlToken` is set, GREEN-API sends it as the **full
> `Authorization` header value**, including the scheme: `Bearer <token>`
> (default) or `Basic <token>`. Compare the **whole header value, scheme
> included**, with a constant-time compare. Don't strip `Bearer ` and compare
> only the token.

```javascript
const crypto = require('crypto');

// webhookUrlToken as entered in GREEN-API: "Bearer abc", "Basic abc", or bare "abc" (sent as "Bearer abc")
function expectedAuthorization(token) {
  return /^(Bearer|Basic) /.test(token) ? token : `Bearer ${token}`;
}

function verifyGreenApiAuthorization(header, token) {
  if (!header || !token) return false;
  const a = Buffer.from(header);
  const b = Buffer.from(expectedAuthorization(token));
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

```

Return `401` on a mismatch. Return `200` quickly on success: GREEN-API retries
undelivered notifications every minute for up to 24 hours, so make handlers
idempotent (dedupe on `idMessage` where present).

> **For complete handlers with tests**, see [examples/express/](https://github.com/hookdeck/webhook-skills/tree/main/skills/green-api-webhooks/examples/express/), [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/green-api-webhooks/examples/nextjs/), [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/green-api-webhooks/examples/fastapi/).

## Common Event Types

Dispatch on the body's `typeWebhook` field:

| `typeWebhook` | Description |
| --- | --- |
| `incomingMessageReceived` | Incoming message or file (`messageData.typeMessage` gives the kind: `textMessage`, `imageMessage`, ...) |
| `outgoingMessageReceived` | Message sent from the phone |
| `outgoingAPIMessageReceived` | Message sent via the API |
| `outgoingMessageStatus` | Status of a sent message (`sent`, `delivered`, `read`, `failed`, `noAccount`, ...) |
| `stateInstanceChanged` | Instance authorization state (`authorized`, `notAuthorized`, `blocked`, ...) |
| `statusInstanceChanged` | Instance socket state (`online`, `offline`) |
| `incomingCall` | Incoming call |

> **For the full list**, see [GREEN-API incoming webhook types](https://green-api.com/en/docs/api/receiving/notifications-format/type-webhook/).

## Environment Variables

```bash
# Exactly what you entered as webhookUrlToken, e.g. "Bearer my-secret" or "Basic dXNlcjpwYXNz".
# A bare token without a scheme is treated as "Bearer <token>".
GREEN_API_WEBHOOK_URL_TOKEN=Bearer your-long-random-secret

```

## Local Development

```bash
# Start tunnel (no account needed)
npx hookdeck-cli listen 3000 green-api --path /webhooks/green-api

```

## Reference Materials

* [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/green-api-webhooks/references/overview.md) - GREEN-API notification types and payload structure
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/green-api-webhooks/references/setup.md) - Set `webhookUrl` / `webhookUrlToken` in the console or with SetSettings
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/green-api-webhooks/references/verification.md) - Authorization header details, IP allowlist, and gotchas