Webhooks

Erfahren Sie alles über die Integration von Webhooks in Dastra

Konzept 👓

Einfach ausgedrückt ermöglichen Webhooks das Auslösen einer Aktion nach einem Ereignis. Sie werden in der Regel verwendet, um Systeme miteinander kommunizieren zu lassen. Es ist die einfachste Art, eine Warnung zu erhalten, wenn etwas in Dastra passiert. Das Ziel ist die Benachrichtigung von Drittanwendungen (API, CRM, Serverless-Funktionen...) in Echtzeit.

Konfiguration 🛠️

Um Ihre Webhooks zu konfigurieren, gehen Sie auf die Seite: https://app.dastra.eu/general-settings/webhooks

Klicken Sie auf „Erstellen Sie eine Webhook-URL"
Geben Sie die Empfangs-URL Ihres Webhooks ein. Weitere Informationen finden Sie im Abschnitt Webhook empfangen.
Geben Sie den betroffenen Mandanten an
Wählen Sie das oder die Ereignisse, die Sie abonnieren möchten. Der Typ der zurückgegebenen Daten unterscheidet sich je nach Ereignistyp. Zum Beispiel können Sie den Webhook bei der Erstellung einer neuen Rechteausübungsanfrage auslösen. In diesem Fall enthält der Body der Anfrage ein JSON
Speichern Sie den Webhook

Sie gelangen zum Detailbildschirm des Webhooks.

Webhook empfangen 🛬

Um die Webhook-Anfragen zu empfangen, müssen Sie einen API-Endpoint zur Erfassung des Ereignisses erstellen. Die durchgeführte Anfrage ist ein POST und ist immer wie folgt strukturiert. Der Body der Anfrage enthält ein JSON mit den Details des ausgelösten Ereignisses.

Hier ist die allgemeine Struktur der gesendeten Antwort:

{
 "webhookId": <id of the webhook configured in dastra>,
 "signatureUrl": "https://yourapi.com/webhooks/handle",
 "userId": <The user whot triggered the event>,
 "eventType": <The id of the event>,
 "eventName": <The label of the event>,
 "data": <Event dynamic data>,
 "date": <date of the event>
}

Ein Timeout von 10 Sekunden wird auf die Anfrage angewendet, nach Ablauf dieser Zeit wird die Anfrage als Fehler gewertet. Der Antwortcode muss 200 sein.

Es kann eine kleine Verzögerung zwischen dem Zeitpunkt des Ereignisses in der Anwendung und dem Auslösen des Webhooks geben (diese Verzögerung ist auf die asynchrone Natur der Webhook-Ausführung in unserer Infrastruktur zurückzuführen). Diese Verzögerung variiert je nach Auslastung unserer Infrastruktur und kann maximal 60-120 Sekunden betragen.

Es gibt derzeit kein System zum erneuten Abspielen fehlgeschlagener Webhooks und damit zur Kompensation einer eventuellen Nichtverfügbarkeit der Webhook-Empfangsserver. In diesem Fall empfehlen wir eine manuelle Synchronisation der fehlgeschlagenen Ereignisse.

Ihre Webhook-URL testen 🧪

Sie können Ihren Webhook unter realen Bedingungen testen, indem Sie auf die Schaltfläche „Testen" klicken.

Webhook absichern 🛡️

Obwohl nicht verpflichtend, wird empfohlen, die eingehende Webhook-Anfrage zu validieren, um potenzielle Angriffe eines Hackers zu vermeiden, der das Netzwerk ausspioniert hat und somit in der Lage wäre, beliebige Daten auf Ihre Webhook-URL zu posten und damit die Erstellung von Elementen in Ihrem System auszulösen oder zu spammen.

Jedes Mal, wenn eine Anfrage zur Änderung oder Löschung eines Dastra-Elements durchgeführt wird, posten wir ein Objekt auf alle URLs, die Sie für das gewünschte Ereignis konfiguriert haben. In jeder POST-Anfrage befindet sich ein Header Dastra-Signature, der serverseitig abgerufen werden kann.

Dieser Header entspricht dem gesamten geposteten JSON, gehasht mit dem Algorithmus HMAC-Sha256 unter Verwendung des Webhook-Validierungsschlüssels.

DastraSignature = HMAC256(<serialisiertes JSON des POST>,<Webhook-Validierungsschlüssel>)

Hier einige Beispiele zur Validierung der Anfrage-Signatur:

error_reporting(E_ALL);
ini_set('display_errors', 1); 
c
$secret = "your dastra validation key";// your secret key
$payload = "";// equest body
$headers = "";// request message headers array

$signature = "";// the HMAC hash key in the HTTP header 'Dastra-Signature'
$result = false;// verification result

if (isset($_POST)) {
    try {
        $payload = file_get_contents('php://input');
        $headers = get_ds_headers();
        if (array_key_exists("Dastra-Signature", $headers)) {
            $signature = $headers["Dastra-Signature"];
            $result = hash_is_valid($secret, $payload, $signature);
            log_result($signature, $payload, $result);
        }
     } catch (Exception $e) {
        logger("\nException: " . $e->getMessage() . "\n");
    }
    header("HTTP/1.1 200 OK");
}

function get_ds_headers()
{
    $headers = array();
    foreach ($_SERVER as $key => $value) {
        if (strpos($key, 'HTTP_') === 0) {
            $headers[str_replace(' ', '', ucwords(str_replace('_', ' ', strtolower(substr($key, 5)))))] = $value;
        }
    }
    return $headers;
}
 
function compute_hash($secret, $payload)
{
    $hexHash = hash_hmac('sha256', $payload, utf8_encode($secret));
    $base64Hash = base64_encode(hex2bin($hexHash));
    return $base64Hash;
}
 
function hash_is_valid($secret, $payload, $verify)
{
    $computed_hash = compute_hash($secret, $payload);
     return hash_equals($verify,$computed_hash);
 }


[HttpPost]
public IActionResult Handle(){
    string dastraSignature = Request.Headers["Dastra-Signature"];
    string key = "Your validation key";
    string payload = GetRequestBody();
}

private static bool ValidateSignature(string signature, string payload, string secret)
{
    using (var hmacsha256 = new HMACSHA256(Encoding.UTF8.GetBytes(secret)))
    {
        var hash = hmacsha256.ComputeHash(Encoding.UTF8.GetBytes(payload));
        var result = Convert.ToBase64String(hash);
    }
    
    return result.Equals(signature)
}

private static string GetRequestBody()
{
    var bodyStream = new StreamReader(Request.InputStream);
    bodyStream.BaseStream.Seek(0, SeekOrigin.Begin);
    var bodyText = bodyStream.ReadToEnd();
    return bodyText;
}

Was passiert, wenn die URL etwas anderes als 200 antwortet

Der Webhook wird automatisch blockiert und als fehlerhaft betrachtet, wenn die Schwelle von 5 Fehlern überschritten wird.

Webhooks mit den APIs einrichten

Die mit Ihrem Konto verknüpften Webhooks abrufen (in allen Mandanten)

Get all webhooks urls configured in workspace

get

Erforderliche Scopes

Dieser Endpunkt erfordert die folgenden Scopes:

: Access database operations

Autorisierungen

OAuth2clientCredentialsErforderlich

Authorization URL: Token URL:

OAuth2authorizationCodeErforderlich

Authorization URL: Token URL:

Abfrageparameter

workspaceIdinteger · int32Optional

Antworten

200

Success

application/json

signatureKeystring · uuidOptional

errorMessagestring · nullableOptional

nbErrorsinteger · int32Optional

dateLastErrorstring · date-time · nullableOptional

inErrorbooleanOptional

idinteger · int32Optional

urlstringErforderlich

workSpaceIdinteger · int32 · nullableOptional

get

/v1/WebHookUrls

GET /v1/WebHookUrls HTTP/1.1
Host: api.dastra.eu
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

200

Success

[
  {
    "signatureKey": "123e4567-e89b-12d3-a456-426614174000",
    "errorMessage": "text",
    "nbErrors": 1,
    "dateLastError": "2026-06-13T15:51:12.076Z",
    "inError": true,
    "workSpace": {
      "id": 1,
      "tenantId": 1,
      "primaryColor": "text",
      "secondaryColor": "text",
      "label": "text",
      "logoUrl": "text",
      "state": "Active",
      "permissions": [
        {
          "name": "text",
          "tenantId": 1,
          "workSpaceId": 1,
          "shortName": "text"
        }
      ],
      "dataSubjectArchivedRetentionDays": 1,
      "nbEntities": 1
    },
    "id": 1,
    "url": "text",
    "workSpaceId": 1,
    "subscribedEvents": [
      "ProcessingCreation"
    ]
  }
]

Erstellen Sie eine neue Webhook-URL mit dem POST-Endpoint. Geben Sie die Ereignisse an, die Sie mit dem Parameter subscribedEvents abonnieren möchten.

Post a new webhook url

post

Erforderliche Scopes

Dieser Endpunkt erfordert die folgenden Scopes:

: Access database operations

Autorisierungen

OAuth2clientCredentialsErforderlich

Authorization URL: Token URL:

OAuth2authorizationCodeErforderlich

Authorization URL: Token URL:

Body

idinteger · int32Optional

urlstringErforderlich

workSpaceIdinteger · int32 · nullableOptional

Antworten

200

Success

application/json

signatureKeystring · uuidOptional

errorMessagestring · nullableOptional

nbErrorsinteger · int32Optional

dateLastErrorstring · date-time · nullableOptional

inErrorbooleanOptional

idinteger · int32Optional

urlstringErforderlich

workSpaceIdinteger · int32 · nullableOptional

post

/v1/WebHookUrls

POST /v1/WebHookUrls HTTP/1.1
Host: api.dastra.eu
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json-patch+json
Accept: */*
Content-Length: 79

{
  "id": 1,
  "url": "text",
  "workSpaceId": 1,
  "subscribedEvents": [
    "ProcessingCreation"
  ]
}

200

Success

{
  "signatureKey": "123e4567-e89b-12d3-a456-426614174000",
  "errorMessage": "text",
  "nbErrors": 1,
  "dateLastError": "2026-06-13T15:51:12.076Z",
  "inError": true,
  "workSpace": {
    "id": 1,
    "tenantId": 1,
    "primaryColor": "text",
    "secondaryColor": "text",
    "label": "text",
    "logoUrl": "text",
    "state": "Active",
    "permissions": [
      {
        "name": "text",
        "tenantId": 1,
        "workSpaceId": 1,
        "shortName": "text"
      }
    ],
    "dataSubjectArchivedRetentionDays": 1,
    "nbEntities": 1
  },
  "id": 1,
  "url": "text",
  "workSpaceId": 1,
  "subscribedEvents": [
    "ProcessingCreation"
  ]
}

Eine Webhook-ID wird Ihnen zurückgegeben

Get webhook by id

get

Erforderliche Scopes

Dieser Endpunkt erfordert die folgenden Scopes:

: Access database operations

Autorisierungen

OAuth2clientCredentialsErforderlich

Authorization URL: Token URL:

OAuth2authorizationCodeErforderlich

Authorization URL: Token URL:

Pfadparameter

idinteger · int32Erforderlich

Antworten

200

Success

application/json

signatureKeystring · uuidOptional

errorMessagestring · nullableOptional

nbErrorsinteger · int32Optional

dateLastErrorstring · date-time · nullableOptional

inErrorbooleanOptional

idinteger · int32Optional

urlstringErforderlich

workSpaceIdinteger · int32 · nullableOptional

get

/v1/WebHookUrls/{id}

GET /v1/WebHookUrls/{id} HTTP/1.1
Host: api.dastra.eu
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

200

Success

{
  "signatureKey": "123e4567-e89b-12d3-a456-426614174000",
  "errorMessage": "text",
  "nbErrors": 1,
  "dateLastError": "2026-06-13T15:51:12.076Z",
  "inError": true,
  "workSpace": {
    "id": 1,
    "tenantId": 1,
    "primaryColor": "text",
    "secondaryColor": "text",
    "label": "text",
    "logoUrl": "text",
    "state": "Active",
    "permissions": [
      {
        "name": "text",
        "tenantId": 1,
        "workSpaceId": 1,
        "shortName": "text"
      }
    ],
    "dataSubjectArchivedRetentionDays": 1,
    "nbEntities": 1
  },
  "id": 1,
  "url": "text",
  "workSpaceId": 1,
  "subscribedEvents": [
    "ProcessingCreation"
  ]
}

Delete webhook url

delete

Erforderliche Scopes

Dieser Endpunkt erfordert die folgenden Scopes:

: Access database operations

Autorisierungen

OAuth2clientCredentialsErforderlich

Authorization URL: Token URL:

OAuth2authorizationCodeErforderlich

Authorization URL: Token URL:

Pfadparameter

idinteger · int32Erforderlich

Antworten

200

Success

Kein Inhalt

delete

/v1/WebHookUrls/{id}

DELETE /v1/WebHookUrls/{id} HTTP/1.1
Host: api.dastra.eu
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

200

Success

Kein Inhalt

Zuletzt aktualisiert vor 2 Tagen

War das hilfreich?