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

# Webhooki

> Otrzymuj powiadomienia w czasie rzeczywistym o wiadomosciach, zdarzeniach dostarczenia i zmianach statusu instancji.

# Webhooki

Webhooki umozliwiaja odbieranie wywolan zwrotnych HTTP w czasie rzeczywistym, gdy zdarzenia wystepuja na Twoich instancjach WhatsApp. Zamiast odpytywac API, Wappfy przesyla zdarzenia na Twoj serwer w momencie ich wystapienia.

## Obslugiwane zdarzenia

Wappfy obsluguje 12 typow zdarzen webhook:

<AccordionGroup>
  <Accordion title="Zdarzenia wiadomosci">
    | Zdarzenie           | Opis                                                                              |
    | ------------------- | --------------------------------------------------------------------------------- |
    | `message.received`  | Otrzymano nowa wiadomosc przychodzaca.                                            |
    | `message.sent`      | Wiadomosc wychodzaca zostala pomyslnie wyslana.                                   |
    | `message.delivered` | Wyslana wiadomosc zostala dostarczona na urzadzenie odbiorcy (podwojny znacznik). |
    | `message.read`      | Wyslana wiadomosc zostala przeczytana przez odbiorce (niebieskie znaczniki).      |
    | `message.failed`    | Wiadomosc wychodzaca nie zostala wyslana.                                         |
    | `message.reaction`  | Ktos zareagowal na wiadomosc za pomoca emoji.                                     |
  </Accordion>

  <Accordion title="Zdarzenia instancji">
    | Zdarzenie               | Opis                                          |
    | ----------------------- | --------------------------------------------- |
    | `instance.connected`    | Instancja pomyslnie polaczyla sie z WhatsApp. |
    | `instance.disconnected` | Instancja utracila polaczenie z WhatsApp.     |
    | `instance.qr`           | Dostepny jest nowy kod QR do zeskanowania.    |
  </Accordion>

  <Accordion title="Zdarzenia grup i kontaktow">
    | Zdarzenie         | Opis                                         |
    | ----------------- | -------------------------------------------- |
    | `group.joined`    | Uczestnik dolaczyl do grupy (w tym sam bot). |
    | `group.left`      | Uczestnik opuscil grupe.                     |
    | `contact.created` | Nowy kontakt zostal zapisany lub wykryty.    |
  </Accordion>
</AccordionGroup>

***

## Tworzenie webhooka

Zarejestruj endpoint webhook, aby zaczac odbierac zdarzenia.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.wappfy.io/api/webhooks \
    -H "X-Api-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "url": "https://your-server.com/webhooks/wappfy",
      "events": ["message.received", "message.sent", "message.delivered"],
      "instance_id": "inst_abc123",
      "secret": "whsec_my_signing_secret",
      "retry_count": 3,
      "timeout_ms": 10000
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.wappfy.io/api/webhooks", {
    method: "POST",
    headers: {
      "X-Api-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      url: "https://your-server.com/webhooks/wappfy",
      events: ["message.received", "message.sent", "message.delivered"],
      instance_id: "inst_abc123",
      secret: "whsec_my_signing_secret",
      retry_count: 3,
      timeout_ms: 10000,
    }),
  });

  const webhook = await response.json();
  console.log(webhook.data.id);
  ```
</CodeGroup>

**Odpowiedz:**

```json theme={null}
{
  "data": {
    "id": "wh_xyz789",
    "url": "https://your-server.com/webhooks/wappfy",
    "events": ["message.received", "message.sent", "message.delivered"],
    "instance_id": "inst_abc123",
    "is_active": true,
    "retry_count": 3,
    "timeout_ms": 10000,
    "created_at": "2026-02-10T12:00:00Z"
  }
}
```

### Opcje konfiguracji

| Pole          | Typ       | Domyslna     | Opis                                                                                                  |
| ------------- | --------- | ------------ | ----------------------------------------------------------------------------------------------------- |
| `url`         | string    | **wymagane** | Adres URL HTTPS, ktory bedzie odbierac zapytania POST webhook.                                        |
| `events`      | string\[] | **wymagane** | Tablica typow zdarzen do subskrypcji.                                                                 |
| `instance_id` | string    | `null`       | Ograniczenie webhooka do konkretnej instancji. Jesli null, odbiera zdarzenia ze wszystkich instancji. |
| `secret`      | string    | `null`       | Sekret uzywany do generowania sygnatur HMAC do weryfikacji danych.                                    |
| `retry_count` | number    | `3`          | Liczba ponownych prob dostarczenia w przypadku niepowodzenia (0-5).                                   |
| `timeout_ms`  | number    | `10000`      | Limit czasu zapytania w milisekundach (1000-30000).                                                   |

<Note>
  Pole `instance_id` jest opcjonalne. Jesli pominiesz je, webhook bedzie odbierac zdarzenia ze **wszystkich** instancji na Twoim koncie.
</Note>

***

## Lista webhookow

```bash theme={null}
curl https://api.wappfy.io/api/webhooks \
  -H "X-Api-Key: YOUR_API_KEY"
```

**Odpowiedz:**

```json theme={null}
{
  "data": [
    {
      "id": "wh_xyz789",
      "url": "https://your-server.com/webhooks/wappfy",
      "events": ["message.received", "message.sent", "message.delivered"],
      "instance_id": "inst_abc123",
      "is_active": true,
      "retry_count": 3,
      "timeout_ms": 10000
    }
  ]
}
```

***

## Aktualizacja webhooka

Zaktualizuj URL, zdarzenia lub konfiguracje istniejacego webhooka.

```bash theme={null}
curl -X PATCH https://api.wappfy.io/api/webhooks/wh_xyz789 \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["message.received", "message.sent", "message.delivered", "message.read"],
    "is_active": true
  }'
```

***

## Usuwanie webhooka

```bash theme={null}
curl -X DELETE https://api.wappfy.io/api/webhooks/wh_xyz789 \
  -H "X-Api-Key: YOUR_API_KEY"
```

***

## Format danych dostarczenia

Gdy wystapi zdarzenie, Wappfy wysyla zapytanie POST na URL webhooka z nastepujaca struktura:

```json theme={null}
{
  "id": "dlv_abc123def456",
  "event": "message.received",
  "instance_id": "inst_abc123",
  "timestamp": "2026-02-10T14:30:00Z",
  "data": {
    "message_id": "BAE5F2C4D3B2A1",
    "chat_id": "5511999998888@s.whatsapp.net",
    "from": "5511999998888@s.whatsapp.net",
    "type": "text",
    "text": "Hello!",
    "timestamp": "2026-02-10T14:30:00Z"
  }
}
```

### Pola danych

| Pole          | Opis                                                                                |
| ------------- | ----------------------------------------------------------------------------------- |
| `id`          | Unikalny identyfikator dostarczenia. Uzyj go do deduplikacji.                       |
| `event`       | Typ zdarzenia, ktore wyzwolilo to dostarczenie.                                     |
| `instance_id` | Instancja, ktora wygenerowala zdarzenie.                                            |
| `timestamp`   | Znacznik czasu ISO 8601 wystapienia zdarzenia.                                      |
| `data`        | Dane specyficzne dla zdarzenia. Zawartosc rozni sie w zaleznosci od typu zdarzenia. |

***

## Weryfikacja sygnatury HMAC

Jesli podales `secret` podczas tworzenia webhooka, kazde dostarczenie bedzie zawierac naglowek `X-Wappfy-Signature` z sygnatura HMAC-SHA256 tresci zapytania.

**Zawsze weryfikuj te sygnature**, aby upewnic sie, ze zapytanie pochodzi od Wappfy i nie zostalo zmodyfikowane.

### Przyklady weryfikacji

<CodeGroup>
  ```javascript Node.js (Express) theme={null}
  const crypto = require("crypto");

  function verifyWebhookSignature(req, secret) {
    const signature = req.headers["x-wappfy-signature"];
    if (!signature) return false;

    const expectedSignature = crypto
      .createHmac("sha256", secret)
      .update(JSON.stringify(req.body))
      .digest("hex");

    return crypto.timingSafeEqual(
      Buffer.from(signature),
      Buffer.from(expectedSignature)
    );
  }

  // Express middleware
  app.post("/webhooks/wappfy", (req, res) => {
    const isValid = verifyWebhookSignature(req, "whsec_my_signing_secret");

    if (!isValid) {
      return res.status(401).json({ error: "Invalid signature" });
    }

    const { event, data } = req.body;
    console.log(`Received event: ${event}`, data);

    // Always respond with 200 quickly to prevent retries
    res.status(200).json({ received: true });
  });
  ```

  ```python Python (Flask) theme={null}
  import hmac
  import hashlib
  import json
  from flask import Flask, request, jsonify

  app = Flask(__name__)
  WEBHOOK_SECRET = "whsec_my_signing_secret"

  def verify_signature(payload, signature):
      expected = hmac.new(
          WEBHOOK_SECRET.encode(),
          json.dumps(payload).encode(),
          hashlib.sha256
      ).hexdigest()
      return hmac.compare_digest(expected, signature)

  @app.route("/webhooks/wappfy", methods=["POST"])
  def handle_webhook():
      signature = request.headers.get("X-Wappfy-Signature", "")
      if not verify_signature(request.json, signature):
          return jsonify({"error": "Invalid signature"}), 401

      event = request.json["event"]
      data = request.json["data"]
      print(f"Received event: {event}", data)

      return jsonify({"received": True}), 200
  ```
</CodeGroup>

<Warning>
  Zawsze uzywaj porownania staloczasowego (jak `timingSafeEqual` lub `hmac.compare_digest`) przy weryfikacji sygnatur, aby zapobiec atakom czasowym.
</Warning>

***

## Polityka ponownych prob

Jesli Twoj serwer nie odpowie kodem statusu `2xx` w skonfigurowanym czasie `timeout_ms`, Wappfy ponowi probe dostarczenia.

| Proba            | Opoznienie |
| ---------------- | ---------- |
| 1. ponowna proba | 10 sekund  |
| 2. ponowna proba | 60 sekund  |
| 3. ponowna proba | 5 minut    |
| 4. ponowna proba | 30 minut   |
| 5. ponowna proba | 2 godziny  |

<Note>
  Ponowne proby sa przerywane po otrzymaniu odpowiedzi `2xx` lub wyczerpaniu `retry_count`. Domyslna liczba ponownych prob to 3.
</Note>

### Przegladanie historii dostarczen

Sprawdz dziennik dostarczen webhooka, aby zobaczyc poprzednie proby dostarczenia i ich wyniki.

```bash theme={null}
curl https://api.wappfy.io/api/webhooks/wh_xyz789/deliveries \
  -H "X-Api-Key: YOUR_API_KEY"
```

**Odpowiedz:**

```json theme={null}
{
  "data": [
    {
      "id": "dlv_abc123def456",
      "event": "message.received",
      "status": "delivered",
      "http_status": 200,
      "attempts": 1,
      "created_at": "2026-02-10T14:30:00Z",
      "delivered_at": "2026-02-10T14:30:01Z"
    },
    {
      "id": "dlv_ghi789jkl012",
      "event": "message.sent",
      "status": "failed",
      "http_status": 500,
      "attempts": 3,
      "created_at": "2026-02-10T14:31:00Z",
      "last_error": "Server returned 500 Internal Server Error"
    }
  ]
}
```

***

## Przyklady danych zdarzen

<AccordionGroup>
  <Accordion title="message.received">
    ```json theme={null}
    {
      "id": "dlv_abc123",
      "event": "message.received",
      "instance_id": "inst_abc123",
      "timestamp": "2026-02-10T14:30:00Z",
      "data": {
        "message_id": "BAE5F2C4D3B2A1",
        "chat_id": "5511999998888@s.whatsapp.net",
        "from": "5511999998888@s.whatsapp.net",
        "type": "text",
        "text": "Hello, I need help with my order",
        "timestamp": "2026-02-10T14:30:00Z"
      }
    }
    ```
  </Accordion>

  <Accordion title="message.delivered">
    ```json theme={null}
    {
      "id": "dlv_def456",
      "event": "message.delivered",
      "instance_id": "inst_abc123",
      "timestamp": "2026-02-10T14:30:05Z",
      "data": {
        "message_id": "BAE5A1B2C3D4E5",
        "chat_id": "5511999998888@s.whatsapp.net",
        "status": "delivered"
      }
    }
    ```
  </Accordion>

  <Accordion title="message.read">
    ```json theme={null}
    {
      "id": "dlv_ghi789",
      "event": "message.read",
      "instance_id": "inst_abc123",
      "timestamp": "2026-02-10T14:31:00Z",
      "data": {
        "message_id": "BAE5A1B2C3D4E5",
        "chat_id": "5511999998888@s.whatsapp.net",
        "status": "read"
      }
    }
    ```
  </Accordion>

  <Accordion title="message.reaction">
    ```json theme={null}
    {
      "id": "dlv_jkl012",
      "event": "message.reaction",
      "instance_id": "inst_abc123",
      "timestamp": "2026-02-10T14:32:00Z",
      "data": {
        "message_id": "BAE5F2C4D3B2A1",
        "chat_id": "5511999998888@s.whatsapp.net",
        "from": "5511999998888@s.whatsapp.net",
        "reaction": "\u2764\ufe0f"
      }
    }
    ```
  </Accordion>

  <Accordion title="instance.connected">
    ```json theme={null}
    {
      "id": "dlv_mno345",
      "event": "instance.connected",
      "instance_id": "inst_abc123",
      "timestamp": "2026-02-10T12:00:00Z",
      "data": {
        "instance_id": "inst_abc123",
        "status": "connected",
        "phone_number": "5511999998888"
      }
    }
    ```
  </Accordion>

  <Accordion title="instance.qr">
    ```json theme={null}
    {
      "id": "dlv_pqr678",
      "event": "instance.qr",
      "instance_id": "inst_abc123",
      "timestamp": "2026-02-10T11:59:00Z",
      "data": {
        "instance_id": "inst_abc123",
        "qr": "data:image/png;base64,iVBORw0KGgo..."
      }
    }
    ```
  </Accordion>

  <Accordion title="group.joined">
    ```json theme={null}
    {
      "id": "dlv_stu901",
      "event": "group.joined",
      "instance_id": "inst_abc123",
      "timestamp": "2026-02-10T15:00:00Z",
      "data": {
        "group_id": "120363012345678901@g.us",
        "participant": "5511888887777@s.whatsapp.net"
      }
    }
    ```
  </Accordion>
</AccordionGroup>

***

## Dobre praktyki

<CardGroup cols={2}>
  <Card title="Odpowiadaj szybko" icon="bolt">
    Zwroc status `200` w ciagu 5 sekund. Przetwarzaj zdarzenie asynchronicznie, aby uniknac limitow czasu.
  </Card>

  <Card title="Deduplikuj" icon="clone">
    Uzyj `id` dostarczenia do wykrywania i pomijania zduplikowanych dostarczen spowodowanych ponownymi probami.
  </Card>

  <Card title="Weryfikuj sygnatury" icon="shield-halved">
    Zawsze waliduj naglowek `X-Wappfy-Signature`, jesli skonfigurowales sekret.
  </Card>

  <Card title="Uzywaj HTTPS" icon="lock">
    Adresy URL webhookow musza uzywac HTTPS. Endpointy HTTP beda odrzucane.
  </Card>
</CardGroup>