# 10.4. Webhook


If you provide `callbackUrl` in `destination`, the system will send a webhook after the report is generated.

### Webhook Request

**Method**: `POST`
**URL**: Your `callbackUrl`
**Headers**:
```
Content-Type: application/json
```

**Body** (identical to GET response):
```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
}
```

**Note**: The `plannedReportUuid` field will be present only if the report was generated from a scheduled report. For one-time reports (created via `POST /report`), this field will be `null` or absent.

### Webhook handling

1. **Webhook is sent when**: `status` reaches a final state (`generated`, `error`, `deleted`, `cancelled`)
2. **Required response**: The server **MUST** respond with HTTP status **200** and body:
  ```json
  {
    "status": "ok"
  }
  ```
3. **Retry**: If the webhook returns an error (status other than 200) or times out, the system will automatically retry delivery

**Example of correct webhook handling** (Node.js/Express):
```javascript
app.post('/webhook/report', (req, res) => {
  const report = req.body;

  console.log(`Report ${report.uuid} has status: ${report.status}`);

  if (report.status === 'generated') {
    // Report ready - download the file or send notification
    console.log(`Report generated at: ${report.generatedAt}`);
  } else if (report.status === 'error') {
    // Generation error
    console.error(`Error generating report ${report.uuid}`);
  }

  // IMPORTANT: You MUST respond 200 with { status: "ok" }
  res.status(200).json({ status: 'ok' });
});
```

---

## Usage examples

### Simple transaction report
```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"
      }
    }
  }'
```

### Report with filtering and webhook
```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"
    }
  }'
```

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

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

### Create scheduled report
```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": "Daily transaction report"
  }'
```

### Update scheduled report
```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"
  }'
```