# 10.4. Webhook


Jeśli podasz `callbackUrl` w `destination`, system wyśle webhook po wygenerowaniu raportu.

### Webhook Request

**Method**: `POST`
**URL**: Twój `callbackUrl`
**Headers**:
```
Content-Type: application/json
```

**Body** (identyczny jak response GET):
```json
{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "plannedReportUuid": "650e8400-e29b-41d4-a716-446655440001",
  "taskName": "report_csv",
  "type": "transaction",
  "status": "generated",
  "settings": {
    "columns": ["transactionInternalId", "transactionAmount"],
    "conditions": {
      "date": {
        "from": 1609459200,
        "to": 1612137599
      },
      "filters": {
        "transactionStatus": ["settled"]
      }
    },
    "destination": {
      "email": ["report@example.com"]
    }
  },
  "generatedAt": 1612137600
}
```

**Uwaga**: Pole `plannedReportUuid` będzie obecne tylko jeśli raport został wygenerowany z zaplanowanego raportu. Dla raportów jednorazowych (utworzonych przez `POST /report`) pole to będzie `null` lub nieobecne.

### Obsługa webhooka

1. **Webhook jest wysyłany gdy**: `status` osiągnie stan końcowy (`generated`, `error`, `deleted`, `cancelled`)
2. **Wymagana odpowiedź**: Serwer **MUSI** odpowiedzieć kodem HTTP **200** z body:
  ```json
  {
    "status": "ok"
  }
  ```
3. **Retry**: Jeśli webhook zwróci błąd (kod inny niż 200) lub timeout, system będzie automatycznie ponawiał wysyłkę

**Przykład poprawnej obsługi webhooka** (Node.js/Express):
```javascript
app.post('/webhook/report', (req, res) => {
  const report = req.body;

  console.log(`Raport ${report.uuid} ma status: ${report.status}`);

  if (report.status === 'generated') {
    // Raport gotowy - pobierz plik lub wyślij powiadomienie
    console.log(`Raport wygenerowany: ${report.generatedAt}`);
  } else if (report.status === 'error') {
    // Błąd generowania
    console.error(`Błąd generowania raportu ${report.uuid}`);
  }

  // WAŻNE: MUSISZ odpowiedzieć 200 z { status: "ok" }
  res.status(200).json({ status: 'ok' });
});
```

---

## Przykłady użycia

### Prosty raport transakcji
```bash
curl -X POST "https://api.example.com/v1/merchant/MERCHANT123/report" \
  -H "Authorization: Basic dXNlcjpwYXNz" \
  -H "Content-Type: application/json" \
  -d '{
    "taskName": "report_csv",
    "type": "transaction",
    "columns": ["transactionInternalId", "transactionAmount", "transactionStatus"],
    "conditions": {
      "date": {
        "from": 1609459200,
        "to": 1612137599,
        "timezone": "Europe/Warsaw"
      }
    }
  }'
```

### Raport z filtrowaniem i webhookiem
```bash
curl -X POST "https://api.example.com/v1/merchant/MERCHANT123/report" \
  -H "Authorization: Basic dXNlcjpwYXNz" \
  -H "Content-Type: application/json" \
  -d '{
    "taskName": "report_csv",
    "type": "transaction",
    "columns": ["transactionInternalId", "transactionAmount", "transactionStatus"],
    "conditions": {
      "date": {
        "from": 1609459200,
        "to": 1612137599,
        "timezone": "Europe/Warsaw"
      },
      "language": "PL",
      "filters": {
        "paymentMethodCode": ["card", "blik"],
        "transactionStatus": ["settled"]
      }
    },
    "formatting": {
      "columnSeparator": ";",
      "numberSeparator": ","
    },
    "destination": {
      "email": ["report@example.com"],
      "callbackUrl": "https://your-domain.com/webhook/report"
    }
  }'
```

### Pobranie raportu
```bash
curl -X GET "https://api.example.com/v1/merchant/MERCHANT123/report/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Basic <key>"
```

### Pobranie pliku raportu
```bash
curl -X GET "https://api.example.com/v1/merchant/MERCHANT123/report/550e8400-e29b-41d4-a716-446655440000/download" \
  -H "Authorization: Basic <key>" \
  -o raport.csv
```

### Tworzenie zaplanowanego raportu
```bash
curl -X POST "https://api.example.com/v1/merchant/MERCHANT123/planned-report" \
  -H "Authorization: Basic <key>" \
  -H "Content-Type: application/json" \
  -d '{
    "taskName": "report_csv",
    "type": "transaction",
    "columns": ["transactionInternalId", "transactionAmount", "transactionStatus"],
    "conditions": {
      "date": {
        "timezone": "Europe/Warsaw"
      },
      "language": "PL"
    },
    "formatting": {
      "columnSeparator": ";",
      "numberSeparator": ","
    },
    "destination": {
      "email": ["report@example.com"]
    },
    "frequency": "day",
    "activeFrom": 1609459200,
    "isActive": true,
    "name": "Dzienny raport transakcji"
  }'
```

### Aktualizacja zaplanowanego raportu
```bash
curl -X PUT "https://api.example.com/v1/merchant/MERCHANT123/planned-report/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Basic <key>" \
  -H "Content-Type: application/json" \
  -d '{
    "isActive": false,
    "frequency": "week"
  }'
```