# Konfiguration (/de/webhooks/configuration)





Jede Organisation hat ein Webhook-Ziel und ein aktives signing secret (Signaturschlüssel). Konfigurieren Sie es in der Platform oder von Ihrem Server aus.

| Detail                | Wert                                                                                             |
| --------------------- | ------------------------------------------------------------------------------------------------ |
| Basis-URL             | `https://api.sandbox.tapaya.com` für die Sandbox, `https://api.tapaya.com` für die Produktion    |
| Authentifizierung     | Server Secret Token in `Authorization`. Siehe [Authentifizierung](/platform-api#authentication). |
| Geltungsbereich       | Ein Ziel pro Organisation                                                                        |
| Zugehöriger Leitfaden | [Verifizieren und testen](/webhooks/receiving)                                                   |

## In der Platform konfigurieren [#configure-in-the-platform]

Öffnen Sie [API Keys](https://platform.tapaya.com/api-keys/) für Ihre Organisation und suchen Sie **Webhooks**.

1. Geben Sie Ihre öffentliche HTTPS-URL ein.
2. Wählen Sie die benötigten Ereignisse aus oder aktivieren Sie **Subscribe to all webhook types**.
3. Aktivieren Sie **Enable** und klicken Sie auf **Save**.
4. Kopieren Sie das signing secret und speichern Sie es auf Ihrem Server.
5. Senden Sie einen [Test-Webhook](/webhooks/receiving#send-a-test-webhook).

<Callout type="warn" title="Das signing secret wird nur einmal angezeigt">
  Kopieren Sie es, wenn Sie das Ziel erstellen oder den Schlüssel rotieren; es kann später nicht mehr abgerufen werden. Es verifiziert nur eingehende Webhooks. Ihr Server Secret Token autorisiert Konfigurationsanfragen.
</Callout>

## Alle Operationen [#all-operations]

| Operation                             | Zweck                                                                                |
| ------------------------------------- | ------------------------------------------------------------------------------------ |
| [Ziel speichern](#save-a-destination) | Das aktuelle Abonnement erstellen oder ersetzen oder sein signing secret rotieren.   |
| [Ziel lesen](#read-a-destination)     | Die aktuelle URL, den Abonnementmodus und den Aktivierungszustand abrufen.           |
| [Ziel löschen](#delete-a-destination) | Das Abonnement sowie seine Zustellwarteschlange und seinen Zustellverlauf entfernen. |

## Ziel verwalten [#manage-the-destination]

<Accordions type="multiple">
  <Accordion title="Ziel speichern" id="save-a-destination">
    **Zweck:** Ihren HTTPS-Empfänger verbinden und die zuzustellenden Ereignisse auswählen.

    ```bash
    curl --request PUT \
      'https://api.sandbox.tapaya.com/integrator/organization/webhook' \
      --header 'Authorization: REPLACE_ME' \
      --header 'Content-Type: application/json' \
      --data '{
        "url": "https://payments.example.com/webhooks/tapaya",
        "eventTypes": ["payment.succeeded", "payment.failed", "payment.refund.succeeded"],
        "subscribeAllEventTypes": false,
        "enabled": true,
        "rotateSecret": false
      }'
    ```

    **Gut zu wissen:**

    * Dies ersetzt die gespeicherte Konfiguration; es fügt keinen zweiten Endpoint hinzu.
    * Bei der Erstellung und einer expliziten Rotation wird `{"signingSecret":"twhsec_..."}` zurückgegeben. Eine gewöhnliche Aktualisierung gibt `{"signingSecret":null}` zurück.
    * Speichern Sie den vollständigen zurückgegebenen Schlüssel einschließlich seines Präfixes. Er wird niemals von GET zurückgegeben.
    * Ihr Token bestimmt die Organisation; senden Sie keine Organisations-ID.

    **Parameter:**

    | Feld                     | Erforderlich | Bedeutung                                                                                                                           |
    | ------------------------ | ------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
    | `url`                    | Ja           | Öffentliche HTTPS-URL auf Port 443 mit bis zu 2.048 Zeichen, ohne eingebettete Zugangsdaten oder Fragment.                          |
    | `eventTypes`             | Ja           | Array mit Namen aus dem [Katalog](/webhooks/events). Wählen Sie mindestens einen aus, sofern Sie nicht alle Typen abonnieren.       |
    | `subscribeAllEventTypes` | Nein         | Standardwert ist `false`. Setzen Sie `true` mit `eventTypes: []`, um alle aktuellen und künftig unterstützten Typen einzuschließen. |
    | `enabled`                | Ja           | Bei `true` werden neue passende Ereignisse festgehalten und Ereignisse aus der Warteschlange gesendet.                              |
    | `rotateSecret`           | Ja           | Bei `true` wird ein neues signing secret erzeugt und zurückgegeben.                                                                 |
  </Accordion>

  <Accordion title="Ziel lesen" id="read-a-destination">
    **Zweck:** Das gespeicherte Abonnement prüfen, ohne sein signing secret offenzulegen.

    ```bash
    curl 'https://api.sandbox.tapaya.com/integrator/organization/webhook' \
      --header 'Authorization: REPLACE_ME'
    ```

    **Gut zu wissen:**

    * GET gibt `404` zurück, wenn diese Organisation kein Ziel hat.
    * Abonnements aller Typen geben ein leeres `eventTypes`-Array mit `subscribeAllEventTypes: true` zurück.
    * Die Antwort enthält niemals das signing secret.
    * Verwenden Sie `availableEventTypes`, um eine Ereignisauswahl zu erstellen, ohne den Katalog fest zu codieren.

    **Rückgabe:**

    | Feld                     | Bedeutung                                                            |
    | ------------------------ | -------------------------------------------------------------------- |
    | `url`                    | Gespeichertes HTTPS-Ziel.                                            |
    | `eventTypes`             | Explizite Abonnements oder ein leeres Array im Modus für alle Typen. |
    | `subscribeAllEventTypes` | Ob aktuelle und künftig unterstützte Typen ausgewählt sind.          |
    | `enabled`                | Ob Webhooks aktiviert sind.                                          |
    | `availableEventTypes`    | Alle Ereignisnamen, die Sie abonnieren können.                       |
  </Accordion>

  <Accordion title="Ziel löschen" id="delete-a-destination">
    **Zweck:** Die Organisation trennen und ihre eingereihten Zustellungen sowie den Zustellverlauf entfernen.

    ```bash
    curl --request DELETE \
      'https://api.sandbox.tapaya.com/integrator/organization/webhook' \
      --header 'Authorization: REPLACE_ME'
    ```

    **Gut zu wissen:**

    * Bei Erfolg wird HTTP `204` ohne Antwortinhalt zurückgegeben.
    * Eine bereits laufende Anfrage kann nach dem Löschen noch eintreffen.
    * Das erneute Erstellen des Ziels erzeugt ein neues signing secret und stellt gelöschte Ereignisse nicht wieder her.
  </Accordion>
</Accordions>

## Zielregeln [#configuration]

### Einstellungen ändern [#configuration-changes]

| Wenn Sie                                          | Was passiert                                                                                                                                                                                                                                         |
| ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Die URL, die Ereignisse oder den Schlüssel ändern | Neue Ereignisse verwenden die neuen Einstellungen. Ereignisse in der Warteschlange behalten die alte URL und den alten Schlüssel; halten Sie daher beide funktionsfähig, bis die Warteschlange abgearbeitet ist.                                     |
| Webhooks deaktivieren                             | Zustellungen aus der Warteschlange werden pausiert und keine neuen Ereignisse festgehalten. Die erneute Aktivierung setzt die Warteschlange fort, aber verpasste Änderungen werden nicht nachträglich bereitgestellt. Tests funktionieren weiterhin. |
| Das Ziel löschen                                  | Ereignisse in der Warteschlange und der Zustellverlauf werden entfernt. Eine bereits laufende Anfrage kann noch eintreffen. Das erneute Erstellen erzeugt ein neues signing secret.                                                                  |

### URL-Anforderungen [#destination-requirements]

* Öffentliches HTTPS auf Port 443. Localhost und private Netzwerke werden zurückgewiesen, und DNS wird bei jedem Verbindungsaufbau erneut geprüft.
* Keine eingebetteten Zugangsdaten, kein Fragment und keine Weiterleitungen.
* Keine benutzerdefinierten Autorisierungsheader. Verifizieren Sie stattdessen die Tapaya-Signatur oder schalten Sie einen serverseitigen Adapter vor eine URL, die einen eigenen Schlüssel benötigt.

## Fehler [#errors]

Konfigurationsanfragen schlagen mit diesen Antworten fehl. Ein Empfänger, der eine Zustellung zurückweist oder verpasst, ist ein anderes Problem; siehe [Fehler behandeln](/webhooks/receiving#handle-errors).

| Antwort       | Bedeutung                                                                                                           |
| ------------- | ------------------------------------------------------------------------------------------------------------------- |
| `400` bei PUT | Ungültige URL, nicht unterstützter Ereignistyp, fehlendes erforderliches Feld oder leere explizite Ereignisauswahl. |
| `401`         | Das Server Secret Token fehlt oder ist ungültig.                                                                    |
| `404` bei GET | Für die authentifizierte Organisation ist kein Ziel vorhanden.                                                      |

Fahren Sie mit der [Signaturprüfung und Testzustellung](/webhooks/receiving) fort.