> ## Documentation Index > Fetch the complete documentation index at: https://docs.didit.me/llms.txt > Use this file to discover all available pages before exploring further. # Webhook-Ziel anlegen – Management API > Lege mit der Didit Management API ein neues Webhook-Ziel an, mit Version, abonnierten Ereignissen und eigenem Signatur-Secret. Pro Aufruf abgerechnet. API-Prompt zum Erstellen eines Webhook-Ziels Prompt in die Zwischenablage kopieren \

\`Register a new webhook destination for my Didit application through the Management API.

Endpoint:
POST https://verification.didit.me/v3/webhook/destinations/

Authentication:
Use the x-api-key header with my Didit API key.

Goal:
\- Create a destination where Didit pushes the events I subscribe to. Each destination is an independent (URL, signing secret, payload version, event subscription) tuple.

Request body (application/json):
\{
"label": "Production session webhooks",        // required, human-readable
"url": "https://yourapp.com/webhooks/didit",   // required, HTTPS URL; must be unique among the application's destinations
"enabled": true,                                 // optional, default true
"webhook_version": "v3",                        // optional, "v1" | "v2" | "v3" — v3 is current/recommended
"subscribed_events": ["status.updated", "data.updated"]  // required, at least one supported event
}

Supported subscribed_events values (no wildcard):
\- status.updated, data.updated — KYC/KYB session lifecycle.
\- user.status.updated, user.data.updated — User entity changes.
\- business.status.updated, business.data.updated — Business entity changes.
\- activity.created — accepted and covered by Try Webhook, but not delivered for live traffic today.
\- transaction.created, transaction.status.updated — Transaction monitoring events.
\- travel_rule.status.updated — a Travel Rule exchange changed status.
\- workflow.compliance_changed — a published workflow's compliance status changed.
\- transaction_rule_suggestions.created — a rule suggestion run proposed new rule changes.
\- The full list, including the Investigator and Authentication families, is at /integration/webhooks#event-types.

Critical: capture secret_shared_key from the response and store it securely.
\- The response includes secret_shared_key — this is the HMAC signing secret used to compute X-Signature, X-Signature-V2, and X-Signature-Simple headers on every webhook delivered to this URL. Verify with X-Signature-V2; X-Signature-Simple is deprecated and authenticates the envelope only.
\- Store the secret from the create response. GET /v3/webhook/destinations/{destination_uuid}/ also returns it in full to your API key, but storing it on create avoids leaking it through follow-up reads.
\- The secret is unique per-destination.
\- The rest of the 201 body has the same shape as GET /v3/webhook/destinations/{destination_uuid}/: secret_last4, health_status "healthy", a summary with zero counts and null times, and created_by_email and created_by_name set to null for a destination created with an API key.

Example call:
curl -X POST "https://verification.didit.me/v3/webhook/destinations/" \
-H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \
-d '{
"label": "Production session webhooks",
"url": "https://yourapp.com/webhooks/didit",
"webhook_version": "v3",
"subscribed_events": ["status.updated", "data.updated"]
}'

Signature verification quick-start (HMAC-SHA256 over the raw request body):
import hmac, hashlib
def verify(body: bytes, signature: str, secret: str) -> bool:
expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, signature)

Always verify against the raw request body, not the parsed JSON. See /integration/webhooks for the full v3 signature scheme.

Failure modes:
\- 400: duplicate URL among the application's destinations, empty subscribed_events, unknown event name, or invalid URL.
\- 401 — missing or malformed x-api-key.
\- 403 — canonical { "detail": "You do not have permission to perform this action." } envelope.

Side effects:
\- A new destination is created and will start receiving deliveries for subscribed_events immediately (assuming enabled: true).
\- Not idempotent — repeated POSTs with different metadata create separate destinations.

For the full integration shape, see /integration/integration-prompt.`

\
Einfügen in Mit Webhook-Zielen können Sie unterschiedliche Didit-Ereignisse an unterschiedliche URLs senden. Jedes Ziel hat einen eigenen `secret_shared_key`, eine eigene `webhook_version` und eine eigene Liste `subscribed_events`.## So funktioniert `subscribed_events``subscribed_events` ist ein Pflicht-Array mit exakten Ereignisnamen. Didit liefert einen Webhook nur dann an dieses Ziel aus, wenn der Wert `webhook_type` im Payload einem der Werte im Array entspricht.- Geben Sie mindestens ein Ereignis an. - Verwenden Sie ausschließlich die unten aufgeführten unterstützten Ereignisnamen. - Fügen Sie jedes Ereignis einzeln hinzu, das Sie zugestellt haben möchten. Es gibt keinen Platzhalterwert wie `*` oder `all`. - Um verschiedene Produktbereiche an unterschiedliche Systeme weiterzuleiten, legen Sie mehrere Ziele mit jeweils unterschiedlichen Listen `subscribed_events` an.## Ereigniskatalog| Ereignis | Abonnieren, wenn Sie Folgendes benötigen | | - | - | | `status.updated` | Änderungen des Status einer Sitzung zur Benutzerverifizierung (KYC) oder Unternehmensverifizierung (KYB). KYB-Payloads enthalten `session_kind: "business"` und `business_session_id`. | | `data.updated` | Die Verifizierungsdaten einer Sitzung werden nach der Erstellung korrigiert oder aktualisiert, z. B. durch Änderungen eines Prüfers an KYC-, Adressnachweis- oder KYB-Daten. | | `user.status.updated` | Eine Benutzer-Entität ändert ihren Status, z. B. zu `ACTIVE`, `FLAGGED` oder `BLOCKED`. | | `user.data.updated` | Das Profil, die Zähler, die Metadaten, die Dokumente oder die aggregierten Verifizierungsfelder einer Benutzer-Entität ändern sich. | | `business.status.updated` | Eine Unternehmens-Entität ändert ihren Status, z. B. nach einer manuellen Prüfung, KYB-Ergebnissen oder einer Aktion auf der Sperrliste. | | `business.data.updated` | Das Profil, die Zähler, die Metadaten, die Registrierungsfelder oder die aggregierten Verifizierungsfelder einer Unternehmens-Entität ändern sich. | | `activity.created` | Wird in `subscribed_events` akzeptiert und ist in **Try Webhook** enthalten, aber Didit liefert es derzeit nicht für den Live-Traffic aus. | | `transaction.created` | Eine Transaktion in der Transaktionsüberwachung wird erstellt und ihre erste Regelauswertung ist abgeschlossen. | | `transaction.status.updated` | Eine Transaktion ändert ihren Status nach Regeln, Analystenprüfung, Abhilfemaßnahmen, Updates von Anbietern oder API- bzw. Konsolenaktionen. Außerdem wird es einmalig gesendet, wenn ein im Hintergrund wiederholtes Krypto-Screening abgeschlossen ist. | | `travel_rule.status.updated` | Ein [Travel Rule](https://docs.didit.me/de/transaction-monitoring/travel-rule.md)-Austausch ändert seinen Status. | | `workflow.compliance_changed` | Der Compliance-Status eines veröffentlichten Workflows ändert sich nach einer erneuten Auswertung. | | `transaction_rule_suggestions.created` | Ein Lauf mit Regelvorschlägen schlägt neue Regeländerungen vor. |Die Ereignisfamilien `investigator.*` (Investigator) und `auth.*` (Authentifizierung) werden ebenfalls akzeptiert. Alle Ereignisse und ihre Payloads finden Sie unter [Webhooks](https://docs.didit.me/de/integration/webhooks.md#ereignistypen).Gängige Abonnementkombinationen:```json theme={null} { "subscribed_events": ["status.updated", "data.updated"] } ``````json theme={null} { "subscribed_events": ["transaction.created", "transaction.status.updated"] } ``````json theme={null} { "subscribed_events": [ "user.status.updated", "user.data.updated", "business.status.updated", "business.data.updated", "activity.created" ] } ```Beispiele für Payloads und Signaturcode finden Sie im [Webhook-Leitfaden](https://docs.didit.me/de/integration/webhooks.md). ## OpenAPI ````yaml de/openapi-25.json POST /v3/webhook/destinations/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: API für Ausweisverifizierung. Authentifizierung über den x-api-key-Header. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/webhook/destinations/: post: tags: - Webhook summary: Webhook-Ziel erstellen description: >- Erstellen Sie ein Webhook-Ziel. Die Antwort enthält das automatisch generierte HMAC-Signaturgeheimnis `secret_shared_key` (später auch über `GET /v3/webhook/destinations/{destination_uuid}/` abrufbar). Senden Sie `subscribed_events` immer mit mindestens einem Ereignis (keine Platzhalter): Eine explizit leere Liste wird mit 400 abgelehnt, und das Weglassen des Feldes erstellt ein Ziel ohne Abonnements, das niemals einen Webhook empfängt. Das Paar `(application, url)` muss unter den Zielen der Anwendung eindeutig sein. operationId: create_webhook_destination requestBody: required: true content: application/json: schema: type: object required: - label - url properties: label: type: string maxLength: 255 description: >- Lesbarer Name, der unter Console → Webhooks angezeigt wird. Hilft bei der Unterscheidung von Zielen, wenn Sie mehrere haben (z. B. „Prod“, „Staging mirror“). url: type: string format: uri description: >- HTTPS-URL, die `POST`-Anfragen empfängt. Muss unter den Zielen der Anwendung eindeutig sein. Verwenden Sie einen stabilen, abgesicherten Endpoint: Didit wiederholt fehlgeschlagene Zustellungen nach einem Backoff-Zeitplan. maxLength: 2000 enabled: type: boolean default: true description: >- Wenn `false`, wird das Ziel gespeichert, aber Didit sendet keine Webhooks dorthin. Nützlich für Staging-Konfigurationen, die Sie vorübergehend pausieren möchten. webhook_version: type: string enum: - v1 - v2 - v3 description: >- Payload-Schema-Version, die Didit sendet. `v3` ist das aktuelle/empfohlene Format; ältere Versionen werden zur Abwärtskompatibilität mit älteren Integrationen beibehalten. subscribed_events: allOf: - $ref: '#/components/schemas/WebhookSubscribedEvents' description: >- Zuzustellende Ereignisse. Faktisch erforderlich: Ein explizites `[]` wird mit 400 abgelehnt, und das Weglassen des Felds erstellt ein Ziel ohne Abonnements, das nichts empfängt. examples: session_updates: summary: Aktualisierungen von Sitzungsstatus und -daten value: label: Production session webhooks url: https://yourapp.com/webhooks/didit webhook_version: v3 subscribed_events: - status.updated - data.updated transaction_updates: summary: Aktualisierungen der Transaktionsüberwachung value: label: Transaction monitoring webhooks url: https://yourapp.com/webhooks/didit-transactions webhook_version: v3 subscribed_events: - transaction.created - transaction.status.updated entity_updates: summary: Aktualisierungen von Benutzer- und Unternehmensentitäten value: label: Entity lifecycle webhooks url: https://yourapp.com/webhooks/didit-entities webhook_version: v3 subscribed_events: - user.status.updated - user.data.updated - business.status.updated - business.data.updated - activity.created responses: '201': description: >- Ziel erstellt. `secret_shared_key` ist das HMAC-Signaturgeheimnis – speichern Sie es jetzt. content: application/json: schema: type: object properties: uuid: type: string format: uuid description: >- Stabiler Ziel-Identifikator. In nachfolgenden Aufrufen als `{destination_uuid}` verwenden. label: type: string url: type: string format: uri enabled: type: boolean webhook_version: type: string enum: - v1 - v2 - v3 secret_shared_key: type: string description: >- Automatisch generiertes HMAC-Signaturgeheimnis, das an dieses Ziel gebunden ist (URL-sicheres Token mit 43 Zeichen). Verwenden Sie es, um die Signatur-Header bei eingehenden Webhooks zu überprüfen. Wird Aufrufern mit API-Schlüssel immer vollständig zurückgegeben; Console-Benutzer benötigen die Berechtigung `read:webhooks`, andernfalls sehen sie eine leere Zeichenfolge. secret_last4: type: string description: >- Die letzten vier Zeichen des aktuellen Signiergeheimnisses des Ziels, damit Sie Geheimnisse voneinander unterscheiden können. Reicht nicht aus, um eine Signatur zu verifizieren. previous_secret_expires_at: type: string format: date-time nullable: true description: >- Wird für 24 Stunden gesetzt, nachdem das Signiergeheimnis des Ziels in der Business Console rotiert wurde. Bis zu diesem Zeitpunkt enthält jede Zustellung an das Ziel auch `X-Signature-Previous`, `X-Signature-V2-Previous` und `X-Signature-Simple-Previous`, erstellt mit dem ersetzten Geheimnis (siehe [Signaturprüfung](/de/integration/webhooks#signaturprüfung)). `null`, wenn in den letzten 24 Stunden keine Rotation stattgefunden hat. subscribed_events: $ref: '#/components/schemas/WebhookSubscribedEvents' created_by_email: type: string nullable: true description: >- E-Mail des Mitglieds der Business Console, das das Ziel erstellt hat. `null` für ein mit einem API-Schlüssel erstelltes Ziel. created_by_name: type: string nullable: true description: >- Name des Mitglieds der Business Console, das das Ziel erstellt hat. `null` bei einem Ziel, das mit einem API-Schlüssel erstellt wurde. created_at: type: string format: date-time updated_at: type: string format: date-time health_status: type: string enum: - healthy - degraded - failing description: >- Zustellungsstatus. `failing`: Bei 3 oder mehr aufeinanderfolgenden Ereignissen ist jeweils der erste Zustellversuch fehlgeschlagen, seit das Ziel zuletzt erfolgreich geantwortet hat (siehe `failing_streak`). `degraded`: nicht failing, aber in den letzten 24 Stunden ist ein Zustellversuch fehlgeschlagen und kein späterer Versuch hat dieses Ereignis zugestellt; ein Wiederholungsversuch oder ein erneutes Senden, das es zustellt, hebt dies auf. `healthy`: weder noch. Unabhängig von `enabled`. Ein fehlgeschlagener Versuch ist ein Versuch, der mit HTTP 400 oder höher beantwortet oder überhaupt nicht beantwortet wurde. failing_streak: type: integer description: >- Wie viele aufeinanderfolgende Ereignisse bei ihrem ersten Zustellversuch fehlgeschlagen sind, seit das Ziel innerhalb der letzten 30 Tage zuletzt erfolgreich geantwortet hat. Wiederholungsversuche werden nicht gezählt, und jeder erfolgreiche Versuch, einschließlich eines Wiederholungsversuchs oder eines erneuten Sendens, beendet die Serie. `0`, wenn seit dem letzten Erfolg kein Ereignis fehlgeschlagen ist. failing_since: type: string format: date-time nullable: true description: >- Wann der erste fehlgeschlagene Versuch der aktuellen `failing_streak` unternommen wurde. `null`, wenn `failing_streak` den Wert `0` hat. last_success_at: type: string format: date-time nullable: true description: >- Wann das Ziel zuletzt innerhalb der letzten 30 Tage auf eine Zustellung mit einem HTTP-Status unter 400 geantwortet hat. `null`, wenn dies in diesem Zeitfenster nicht der Fall war. environment: type: string enum: - live - sandbox description: Umgebung der Anwendung, zu der das Ziel gehört. summary: type: object description: >- Zustellungsmetriken für die letzten `metrics_window_days` (30) Tage. `last_delivery_at` ist der letzte Versuch, unabhängig davon, wann er unternommen wurde. properties: total_deliveries: type: integer failed_deliveries: type: integer error_rate_percentage: type: integer min_response_time_ms: type: integer nullable: true avg_response_time_ms: type: integer nullable: true max_response_time_ms: type: integer nullable: true last_delivery_at: type: string format: date-time nullable: true metrics_window_days: type: integer description: >- Länge des Zeitfensters in Tagen, das von den anderen zusammenfassenden Metriken abgedeckt wird. Immer `30`. examples: Created: value: uuid: 11111111-2222-3333-4444-555555555555 label: Production session webhooks url: https://yourapp.com/webhooks/didit enabled: true webhook_version: v3 secret_shared_key: tno2NTeRC1ZK3sBOYlBJDyEzBVENl3pQ1AcZyAW0xnQ secret_last4: 0xnQ previous_secret_expires_at: null subscribed_events: - status.updated - data.updated created_by_email: null created_by_name: null created_at: '2026-05-17T10:00:00Z' updated_at: '2026-05-17T10:00:00Z' health_status: healthy failing_streak: 0 failing_since: null last_success_at: null environment: live summary: total_deliveries: 0 failed_deliveries: 0 error_rate_percentage: 0 min_response_time_ms: null avg_response_time_ms: null max_response_time_ms: null last_delivery_at: null metrics_window_days: 30 '400': description: >- Validierung fehlgeschlagen – normalerweise eine doppelte URL, fehlende/ungültige `subscribed_events` oder ein unbekannter Ereignisname. content: application/json: examples: Duplicate URL: value: url: - >- This webhook destination already exists for the application. Empty events list: value: subscribed_events: - At least one subscribed event is required. Unknown event: value: subscribed_events: - 'Unsupported webhook events: foo.bar' '403': description: >- API-Schlüssel fehlt, ist fehlerhaft, abgelaufen oder für eine andere Anwendung gültig. Ein fehlender Schlüssel gibt `403` zurück; ein falscher, widerrufener oder abgelaufener Schlüssel gibt `401` zurück. content: application/json: examples: Forbidden: value: detail: You do not have permission to perform this action. '429': description: >- Rate-Limit überschritten; drosseln Sie die Anfragen und wiederholen Sie den Versuch. content: application/json: examples: Throttled: value: detail: Request was throttled. Expected available in 30 seconds. security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: curl source: >- curl -X POST 'https://verification.didit.me/v3/webhook/destinations/' \ -H 'x-api-key: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "label": "Production session webhooks", "url": "https://yourapp.com/webhooks/didit", "webhook_version": "v3", "subscribed_events": ["status.updated", "data.updated"] }' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.webhooks.destinations.create( label="Production session webhooks", url="https://yourapp.com/webhooks/didit", webhook_version="v3", subscribed_events=["status.updated", "data.updated"], ) print(result) - lang: javascript label: Node.js source: |- import Didit from "@didit-protocol/sdk-node"; // Reads DIDIT_API_KEY. const didit = new Didit(); const result = await didit.webhooks.destinations.create({ label: "Production session webhooks", url: "https://yourapp.com/webhooks/didit", webhook_version: "v3", subscribed_events: ["status.updated", "data.updated"], }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Webhooks.Destinations.Create(ctx, didit.WebhooksDestinationsCreateParams{\n\tLabel: \"Production session webhooks\",\n\tURL: \"https://yourapp.com/webhooks/didit\",\n\tWebhookVersion: didit.Some(didit.WebhooksDestinationsCreateParamsWebhookVersion(\"v3\")),\n\tSubscribedEvents: didit.Some([]didit.WebhookEvent{didit.WebhookEvent(\"status.updated\"), didit.WebhookEvent(\"data.updated\")}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: >- import java.util.List; import me.didit.Didit; import me.didit.types.WebhookEvent; import me.didit.types.WebhooksDestinationsCreateParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.webhooks().destinations().create(WebhooksDestinationsCreateParams.builder() .label("Production session webhooks") .url("https://yourapp.com/webhooks/didit") .webhookVersion(WebhooksDestinationsCreateParams.WebhookVersion.of("v3")) .subscribedEvents(List.of(WebhookEvent.of("status.updated"), WebhookEvent.of("data.updated"))) .build()); System.out.println(result); - lang: php label: PHP source: |- webhooks->destinations->create([ 'label' => 'Production session webhooks', 'url' => 'https://yourapp.com/webhooks/didit', 'webhook_version' => 'v3', 'subscribed_events' => ['status.updated', 'data.updated'], ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.webhooks.destinations.create( label: "Production session webhooks", url: "https://yourapp.com/webhooks/didit", webhook_version: "v3", subscribed_events: ["status.updated", "data.updated"] ) puts result.to_h - lang: csharp label: .NET source: >- using System; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); var result = await client.Webhooks.Destinations.CreateAsync(new WebhooksDestinationsCreateParams { Label = "Production session webhooks", Url = "https://yourapp.com/webhooks/didit", WebhookVersion = new WebhooksDestinationsCreateParamsWebhookVersion("v3"), SubscribedEvents = new WebhookEvent[] { "status.updated", "data.updated" }, }); Console.WriteLine(JsonSerializer.Serialize(result)); components: schemas: WebhookSubscribedEvents: type: array description: >- Ereignisfilter für dieses Webhook-Ziel. Didit stellt nur Webhooks zu, deren Ereignistyp exakt mit einem dieser Werte übereinstimmt – es gibt kein Wildcard-Abonnement. Beim Senden muss die Liste mindestens ein gültiges Ereignis enthalten (ein explizites `[]` wird mit 400 abgelehnt); ein Ziel mit leerer Liste (Feld bei der Erstellung weggelassen) empfängt nichts. Bei einer Aktualisierung wird die Liste vollständig ersetzt, niemals zusammengeführt. minItems: 1 uniqueItems: true items: $ref: '#/components/schemas/WebhookEvent' example: - status.updated - data.updated WebhookEvent: type: string description: >- Name des unterstützten Webhook-Ereignisses. Verwenden Sie genau diese Zeichenfolgen in `subscribed_events`; nicht unterstützte Werte werden abgelehnt. enum: - status.updated - data.updated - user.status.updated - user.data.updated - business.status.updated - business.data.updated - activity.created - transaction.created - transaction.status.updated - travel_rule.status.updated - workflow.compliance_changed - transaction_rule_suggestions.created - auth.signup - auth.login - auth.login_failed - auth.password_reset_requested - auth.password_reset_completed - auth.mfa_changed - auth.new_device - auth.account_locked - investigator.report.ready - investigator.decision.automated - investigator.decision.overridden - investigator.decision.contested - investigator.question.raised - investigator.automation.paused - investigator.rfi.answered - investigator.rfi.overdue - investigator.drift.detected - investigator.sla.breached - investigator.qa.failed - investigator.external.report.ready securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- Der API-Schlüssel Ihrer Anwendung, aus Entwickler -> API-Schlüssel in der Business Console. Der Primärschlüssel hat Vollzugriff. Ein benannter Schlüssel kann im Geltungsbereich eingeschränkt werden: keine, Lese- oder Schreibberechtigung pro Ressource, beschränkt auf bestimmte Workflows oder genehmigte Sitzungen, auf eine Liste von IP-Adressen und auf ein Ablaufdatum. 401 bedeutet, dass der Schlüssel falsch, widerrufen oder abgelaufen ist; 403 bedeutet, dass kein Schlüssel gesendet wurde, der Schlüssel keinen Zugriff auf diese Ressource oder Aktion hat oder die Anfrage von einer Adresse außerhalb seiner IP-Liste stammte; 404 bei einer Sitzungsroute bedeutet, dass die Sitzung außerhalb der Workflows oder Status des Schlüssels liegt. Ein Schlüssel ohne Medienzugriff erhält Bild-, Video- und PDF-URLs als null, und ein Schlüssel ohne Schreibberechtigung für Sitzungen erhält Sitzungslinks und Token als null. Siehe https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.