Zum Hauptinhalt springen

Public API – Webhooks

Lass dich benachrichtigen, sobald ein Trauerfall einen Prozessschritt erreicht – mit Payload, Signatur und Zustellregeln.

Verfasst von Support Team

Mit Webhooks meldet RIP App Business deinem System, dass ein Trauerfall einen bestimmten Prozessschritt erreicht hat – zum Beispiel „Abholung“. Dein System muss dafür nicht ständig nachfragen. Webhooks funktionieren mit Make, Zapier, n8n oder einem eigenen Server.

Webhooks sind Teil des Moduls Automatisierung, nicht der Public API. Du kannst sie auch ohne Public API nutzen.

Webhook einrichten

Voraussetzungen: Das Modul Automatisierung ist im Shop gebucht, und es gibt eine Bestattungsart mit Prozessschritten.

  1. Öffne Einstellungen → Automatisierungen.

  2. Klicke bei Webhooks auf Neuer Webhook.

  3. Gib eine Bezeichnung ein, zum Beispiel „Abholung an Warenwirtschaft“.

  4. Wähle unter Wenn … die Bestattungsart und den Prozess-Schritt.

  5. Trage unter Dann … die Webhook-URL ein. Sie muss mit https:// oder http:// beginnen. Nutze immer https://.

  6. Klappe HMAC-Secret auf und trage einen geheimen Schlüssel ein (empfohlen).

  7. Mit Testen schickst du sofort eine Beispielnachricht an die URL. Bei Erfolg erscheint Webhook zugestellt (HTTP 200).

  8. Lass Aktiviert eingeschaltet und klicke auf Regel erstellen.

Ein Webhook gilt immer für eine Bestattungsart und einen Schritt. Für mehrere Schritte legst du mehrere Webhooks an – auch mit derselben URL. Unter Zustellhistorie siehst du für jeden Webhook die letzten Zustellungen mit HTTP-Status.

Wann ein Webhook gesendet wird

Es gibt ein Ereignis: step_reached – ein Trauerfall hat den Schritt erreicht, an dem der Webhook hängt.

Gesendet wird, wenn der Schritt

  • automatisch erreicht wird, also durch einen Trigger wie RIP Tag, Ankunft oder Abfahrt an Abhol- oder Lieferadresse oder einen Ort, oder

  • von Hand gesetzt wird – in Web, App oder über die API (POST /cases/{uuid}/step oder current_step_index in PATCH /cases/{uuid}).

Gut zu wissen:

  • Setzt jemand den Schritt erneut oder springt zurück und wieder vor, wird der Webhook erneut gesendet.

  • Setzt jemand von Hand einen späteren Schritt, kommt nur die Nachricht für diesen Schritt – nicht für die übersprungenen.

  • Schaltet die Automatik mehrere Schritte nacheinander weiter, kommt für jeden erreichten Schritt mit Webhook eine eigene Nachricht – in der Reihenfolge der Schritte.

  • Bei pausierter Automatik werden keine Schritte automatisch erreicht, also auch keine Webhooks gesendet. Von Hand gesetzte Schritte lösen weiterhin aus.

  • Kein Webhook kommt beim Anlegen, Ändern, Archivieren oder Abschließen eines Falls und bei Terminen oder Dokumenten.

Die Anfrage

RIP App Business schickt einen POST an deine URL:

POST /webhooks/rip HTTP/1.1
Host: erp.bestattungen-berger.de
Content-Type: application/json
User-Agent: RIP-App-Automation/1.0
X-RIP-Signature: sha256=5f1c0b8e3a…

X-RIP-Signature ist nur dabei, wenn du ein HMAC-Secret hinterlegt hast.

Payload

{
  "event": "step_reached",
  "step_index": 1,
  "step_name": "Abholung",
  "case": {
    "uuid": "3f8c2a91-6d4e-4b7a-9c15-8e2f0b6d1a47",
    "first_name": "Gisela",
    "last_name": "Neumann",
    "date_of_birth": "1938-04-02",
    "date_of_death": "2026-11-10",
    "burial_type": "Feuerbestattung",
    "public_link": "https://de.rip-app.business/t/3f8c2a91-6d4e-4b7a-9c15-8e2f0b6d1a47"
  },
  "pickup_location": {
    "address": "Seniorenresidenz Am Lindenpark, Parkstraße 8, 14052 Berlin",
    "latitude": 52.516276,
    "longitude": 13.277041,
    "maps_url": "https://maps.google.com/?q=52.51627600,13.27704100"
  },
  "contact": {
    "name": "Lea Hoffmann",
    "email": "[email protected]",
    "phone": "+49 30 5550123"
  },
  "rip_tag": {
    "uuid": "e4a1c9d2-7b3f-4e8a-9d6c-2f5b8a1e0c74",
    "startcode": "K7M2-9QXA",
    "gps": {
      "latitude": 52.516301,
      "longitude": 13.277012,
      "seen_at": "2026-11-11T08:14:57+01:00",
      "maps_url": "https://maps.google.com/?q=52.516301,13.277012"
    }
  },
  "organization": "Bestattungen Berger",
  "triggered_at": "2026-11-11T07:15:02+00:00"
}

Feld

Typ

Beschreibung

event

String

Immer step_reached

step_index

Integer

Index des erreichten Schritts (0 = erster Schritt) – wie current_step_index in der API

step_name

String

Name des Schritts

case.uuid

String

UUID des Trauerfalls. Damit holst du über die API weitere Daten.

case.first_name, case.last_name

String

Name der verstorbenen Person

case.date_of_birth, case.date_of_death

String oder null

YYYY-MM-DD

case.burial_type

String

Name der Bestattungsart

case.public_link

String

Link für Angehörige

pickup_location

Objekt oder null

Abholadresse mit address, latitude, longitude, maps_url. Ohne Koordinaten nur address.

contact

Objekt oder null

Hauptverantwortliche Person mit name, email, phone (je nach Profil auch null)

rip_tag

Objekt oder null

Verbundener RIP Tag mit uuid, startcode und gps

rip_tag.gps

Objekt oder null

Letzte bekannte Position mit latitude, longitude, seen_at (ISO 8601) und maps_url – immer genau, unabhängig von der Einstellung „Ungefähr“ im Link

organization

String

Name deines Unternehmens

triggered_at

String

Zeitpunkt des Versands in UTC, ISO 8601

Die Payload enthält personenbezogene Daten. Verwende nur https://-URLs und Ziele, mit denen du einen Auftragsverarbeitungsvertrag hast, falls nötig.

Signatur prüfen

Mit HMAC-Secret signiert RIP App Business jede Nachricht: X-RIP-Signature enthält sha256= und den HMAC-SHA256 des unveränderten Request-Bodys mit deinem Secret als Schlüssel, hexadezimal in Kleinbuchstaben.

So prüfst du die Signatur:

  1. Lies den Body roh, bevor du ihn als JSON parst.

  2. Berechne sha256= + HMAC-SHA256(Body, Secret) als Hex.

  3. Vergleiche mit dem Header in konstanter Zeit. Weicht er ab, antworte mit 401 und verwirf die Nachricht.

Node.js (Express)

import crypto from "node:crypto";
import express from "express";

const app = express();

app.post("/webhooks/rip", express.raw({ type: "application/json" }), (req, res) => {
  const received = req.get("X-RIP-Signature") ?? "";
  const expected =
    "sha256=" +
    crypto.createHmac("sha256", process.env.RIP_WEBHOOK_SECRET).update(req.body).digest("hex");

  const valid =
    received.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
  if (!valid) return res.sendStatus(401);

  res.sendStatus(204); // sofort bestätigen, danach verarbeiten
  const event = JSON.parse(req.body.toString("utf8"));
  if (event.test) return; // Testnachricht aus den Einstellungen
  queue.push(event);      // z. B. in eine Warteschlange legen
});

PHP

<!--?php
$payload  = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $payload, getenv('RIP_WEBHOOK_SECRET'));
$received = $_SERVER['HTTP_X_RIP_SIGNATURE'] ?? '';

if (!hash_equals($expected, $received)) {
    http_response_code(401);
    exit;
}

http_response_code(204);
$event = json_decode($payload, true);
if (!empty($event['test'])) {
    exit; // Testnachricht aus den Einstellungen
}
// $event['case']['uuid'], $event['step_name'] …
-->

Die Signatur enthält keinen Zeitstempel. Wenn du dich gegen wiederholt eingespielte Nachrichten schützen willst, verwirf Nachrichten mit einem alten triggered_at.

Zustellung

Regel

Wert

Methode

POST mit JSON-Body

Zeitlimit

5 Sekunden

Erfolg

Jeder Statuscode 200 bis 299

Wiederholung

Keine. Schlägt die Zustellung fehl, wird sie nicht erneut versucht.

TLS

Das Zertifikat deiner URL muss gültig sein.

Daraus folgt für deinen Empfänger:

  • Antworte sofort mit 2xx und verarbeite danach. Die Zustellung läuft im selben Moment wie die auslösende Aktion – ein langsamer Empfänger bremst zum Beispiel die Antwort auf POST /cases/{uuid}/step.

  • Rechne mit verpassten Nachrichten. War dein Server nicht erreichbar, gleiche den Stand über die API ab: GET /cases liefert current_step_index aller offenen Fälle.

  • Rechne mit doppelten Nachrichten. Wird ein Schritt erneut gesetzt, kommt eine neue Nachricht. Wenn du jeden Schritt nur einmal verarbeiten willst, merke dir die Kombination aus case.uuid und step_index.

Fehlgeschlagene Zustellungen siehst du in der Zustellhistorie des Webhooks.

Testnachricht

Testen in den Einstellungen schickt eine Nachricht mit Beispieldaten (Max Mustermann) und dem zusätzlichen Feld "test": true. Sie wird mit deinem HMAC-Secret signiert, aber nicht in der Zustellhistorie gespeichert. Ignoriere Nachrichten mit "test": true in deiner Verarbeitung.

Webhook ändern oder abschalten

Öffne den Webhook unter Einstellungen → Automatisierungen. Mit Aktiviert schaltest du ihn vorübergehend ab, ohne ihn zu löschen. Leerst du das Feld HMAC-Secret und speicherst, werden Nachrichten danach ohne Signatur gesendet.

Hat dies deine Frage beantwortet?