# Webhooks (/de/webhooks)



Webhooks benachrichtigen Ihren Server über Änderungen in Ihrer Tapaya-Organisation. Verwenden Sie dieselbe Integration für Zahlungen vor Ort und Online-Zahlungen, unabhängig vom Zahlungsabwickler.

## Funktionsweise [#how-it-works]

<WebhookLifecycle senderLabel="Tapaya" receiverLabel="Ihr Server" label="Eine bestätigte Änderung stellt ein Ereignis in die Warteschlange. Tapaya signiert und sendet es. Ihr Empfänger verifiziert und speichert es. Eine 2xx-Antwort bestätigt die Zustellung; bei Fehlern wird ab dem Sendeschritt wiederholt, bis zu 12 Versuche, dann wird gestoppt." event="Gespeicherte Änderung" queue="Ereignis eingereiht" send="Signierter POST" receive="Verifizieren und speichern" delivered="Zugestellt" />

Konfigurieren Sie ein HTTPS-Ziel pro Organisation und wählen Sie die benötigten Ereignisse aus. Tapaya sendet einen HTTP-`POST` mit einem JSON-Snapshot und einer Signatur. Verifizieren Sie die Signatur, speichern Sie das Ereignis und geben Sie eine erfolgreiche Antwort zurück, bevor Sie Ihre Geschäftslogik ausführen.

Sie können einzelne Typen oder alle unterstützten Typen abonnieren. Ein Abonnement aller Typen empfängt auch künftig neu unterstützte Typen. Ignorieren Sie daher Typen, die Ihre Anwendung nicht kennt.

## Schnelle Integration [#quick-integration]

<div className="fd-steps [&_h3]:fd-step">
  ### Ziel speichern [#save-a-destination]

  Öffnen Sie in der Platform **API Keys** und dann **Webhooks**. Geben Sie Ihre HTTPS-URL ein, wählen Sie die benötigten Ereignisse aus und speichern Sie. Kopieren Sie das signing secret (Signaturschlüssel) sofort; es wird nur einmal angezeigt. Siehe [Konfiguration](/webhooks/configuration).

  ### Jede Anfrage verifizieren [#verify-each-request]

  Berechnen Sie mit Ihrem signing secret einen HMAC-SHA256 aus dem Zeitstempel, einem Punkt und dem ursprünglichen Anfrageinhalt und vergleichen Sie ihn mit `X-Tapaya-Signature`. Siehe [Signatur prüfen](/webhooks/receiving#check-the-signature).

  ### Ereignis speichern, dann 2xx zurückgeben [#store-the-event-then-return-2xx]

  Speichern Sie das Ereignis mit einer eindeutigen `id`, antworten Sie innerhalb von 10 Sekunden mit `2xx` und verarbeiten Sie es anschließend. Siehe [Speichern und bestätigen](/webhooks/receiving#store-and-acknowledge).

  ### Test-Webhook senden [#send-a-test-webhook]

  Verwenden Sie auf derselben Seite die Testaktion, um eine signierte Anfrage `webhook.test` zu senden. Siehe [Test-Webhook senden](/webhooks/receiving#send-a-test-webhook).
</div>

## Ereignishülle [#event-envelope]

Jedes Ereignis verwendet diese gemeinsame Hülle (Envelope). Der Ressourcen-Snapshot in `data` hängt vom Typ ab.

```json
{
  "id": "019a0000-0000-7000-8000-000000000001",
  "type": "payment.succeeded",
  "apiVersion": "1",
  "organizationId": "019a0000-0000-7000-8000-000000000002",
  "merchantId": "019a0000-0000-7000-8000-000000000005",
  "createdAt": "2026-10-30T12:00:00.000000Z",
  "data": {
    "payment": {
      "id": "019a0000-0000-7000-8000-000000000003",
      "token": "example_payment_token",
      "merchantId": "019a0000-0000-7000-8000-000000000005",
      "status": "success",
      "statusId": 2,
      "requestedAmount": 10000,
      "requestedCurrencyId": 203,
      "settlementAmount": 10000,
      "settlementCurrencyId": 203
    }
  }
}
```

| Feld             | Bedeutung                                                                                                                        |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `id`             | Eindeutige Ereignis-ID. Verwenden Sie sie zur Deduplizierung der Zustellungen. Wiederholungen behalten dieselbe ID.              |
| `type`           | Ereignisname aus dem [Ereigniskatalog](/webhooks/events).                                                                        |
| `apiVersion`     | Kennung des Payload-Schemas, derzeit die Zeichenfolge `"1"`.                                                                     |
| `organizationId` | Organisation, der das Ereignis gehört. Prüfen Sie, ob sie Ihrer Integration entspricht.                                          |
| `merchantId`     | Händler, dem die Ressource gehört. Kann bei älteren Zahlungen mit ungeklärter Zuordnung oder bei einem Diagnosetest `null` sein. |
| `createdAt`      | UTC-Zeitpunkt, zu dem das Ereignis festgehalten wurde, nicht der Zustellzeitpunkt.                                               |
| `data`           | Unveränderlicher Ressourcen-Snapshot zum Zeitpunkt des Festhaltens.                                                              |

Beträge sind ganzzahlige Werte in der kleinsten Einheit der Währung des Feldes. Beispielsweise bedeutet `10000` mit der numerischen ISO-4217-Währungs-ID `203` einen Betrag von 100,00 CZK. Angeforderte Beträge und Abrechnungsbeträge können unterschiedliche Währungen verwenden.

Jeder Ereignistyp legt seinen eigenen Snapshot in `data` ab. Alle Payload-Strukturen und Statuswerte finden Sie unter [Ereignistypen](/webhooks/events).

## Zustellregeln [#delivery-rules]

Tapaya sendet ein Ereignis, sobald seine Änderung gespeichert ist, und sendet es so lange erneut, bis Ihr Server mit `2xx` antwortet.

| Regel          | Verhalten                                                                                                                |
| -------------- | ------------------------------------------------------------------------------------------------------------------------ |
| Bestätigung    | Jede `2xx`-Antwort innerhalb von 10 Sekunden. Weiterleitungen werden nicht verfolgt.                                     |
| Wiederholungen | Bis zu 12 Versuche über etwa 20 Stunden, mit Wartezeiten von 1, 2, 4, 8, 16, 32, 64, 128, 256, 360 und 360 Minuten.      |
| Reihenfolge    | Nicht garantiert. Die Zustellung erfolgt mindestens einmal, rechnen Sie also mit Duplikaten und älteren Snapshots.       |
| Parallelität   | 2 Anfragen gleichzeitig pro Organisation, gemeinsam mit manuellen Tests. Weitere Ereignisse warten in der Warteschlange. |

Eine fehlgeschlagene Zustellung ändert nie die Zahlung selbst, und frühere Zustellungen können nicht erneut abgespielt werden. Um nach einem Ausfall aufzuholen, lesen Sie den aktuellen Stand über die [Zahlungs- und Händler-APIs](/platform-api/reporting).

## Integration beginnen [#start-integrating]

<Cards>
  <Card title="Ziel konfigurieren" href="/webhooks/configuration">
    Legen Sie die URL fest, wählen Sie Ereignisse aus und speichern Sie Ihr signing secret (Signaturschlüssel).
  </Card>

  <Card title="Ereignistypen durchsuchen" href="/webhooks/events">
    Finden Sie den genauen Auslöser jedes Zahlungs-, Händler- und Onboarding-Ereignisses.
  </Card>

  <Card title="Verifizieren und testen" href="/webhooks/receiving">
    Prüfen Sie Signaturen und senden Sie einen Diagnose-Webhook.
  </Card>
</Cards>