Webhooks verstehen - Beispiel?

[beta20]

Hallo zusammen,

ich würde gerne Webhooks näher verstehen, finde dazu allerdings relativ wenig brauchbares im Internet.
Das Prinzip ist eigentlich klar:

1)
- Meine App erstellt z.B. eine Bestellung.
- Anschließend wird ein Webhook erzeugt
-> Genau hier entsteht schon die erste Frage:
Wie sieht das Programmiertechnisch aus? Hat hier jemand einen Beispiel Code?
Wenn ich es richtig verstehe, wird der Request an eine bestimmte URL gesendet. Beispiel: https://mydomain.com/webhook

2) Endpoint
Auch hier die Frage: Wie kann so ein Endpoint programmiertechnisch aussehen?
Insbesondere die Frage, die sich mir ergibt ist:
a) Was genau ist ein Event? Ich sehe events wie "order_created".
b) Wie wird die "Order" an den Webhook gesendet?

Ein konkretes Beispiel (Code) würde mir sehr sehr helfen um das Prinzip zu verstehen. Also:

1) Senden des Webhooks, inkl:
a) Event = "orderCreated"
b) Order Objekt senden

2) Empfangen des Webhooks
a) Wie sieht die Methode aus
b) Woran erkennt die Methode, dass es sich um das Event "orderCreated" handelt
c) Wie wird das "Order" Objekt übermittelt?


Eine letzte Frage:
a) Wenn ich mehrere Webhooks entgegen nehmen möchte. Habe ich dann eine Methode? Und es wird dann eben das "Event" per if Statements geprüft?
b) Wie sieht dann die Übermittlung der Parameter aus? Wenn ich nicht nur "Order" für das Event "orderCreated" habe, sondern auch ein Event "customerCreated" und möchte eben Customer übergeben.

Wie gesagt, es geht mir hier wirklich um einen Beispiel Code für das oben aufgezeigte Szenario. Was das Webhook dann wiederum anstößt ist dann eben eine andere Sache. Ich vermute das sind ein paar Zeilen Code? Zudem auch die Frage, welche libs ich benötige?

Besten Dank für die Hilfe und Denkanstöße

 

[mrBrown]

Webhooks - was genau ist das und was kann damit JAVA

Hallo, ich habe eine Frage was Webhooks angeht. Prinzipiell verstehe ich das Konzept. Es wird ein Event ausgelöst, z-B. Order wurde in einen anderen Status versetzt. Nun wird eine vordefinierte URL aufgerufen, anschließend kann das 3 Party Programm weitere Dinge machen (Rechnung verschicken...

www.java-forum.org

 

[beta20]

danke, aber wie gesagt: es geht mir um ein konkretes Beispiel, insbesondere auch mit den "Events"

 

[mihe7]

finde dazu allerdings relativ wenig brauchbares im Internet.

Keine Ahnung, ob das so ist aber wenn, dann vielleicht, weil daran nichts besonderes ist.

Technisch hast Du auf der einen Seite einen Server, der einen Request entgegennimmt und auf der anderen Seite einen Server, der einen Request sendet. Fertig. Was Du da wie überträgst, bleibt Dir überlassen.

 

[httpdigest]

True, true!
Deine Frage ist in etwa so wie: "Kann mir jemand zeigen, wie ich einen Artikel in einem Supermarkt an der Klasse bar bezahle, wenn der Artikel exakt €1,48 kostet? Ich finde zwar viele viele Videos von Leuten, die zeigen, wie man generell an einer Kasse bar bezahlt, aber es sind niemals exakt €1,48... ich BRAUCHE EIN BEISPIEL FÜR €1,48"

Analogien: Das "an der Kasse bar bezahlen" ist das Senden und Empfangen eines HTTP Requests. Die €1,48 sind der spezielle Anwendungsfall, dass man mit dem Request wiederum irgendwas 'triggern' will, was man manchmal einen "Webhook" nennen kann.

 

[beta20]

Danke für die Antworten.
Wie gesagt: ein einfaches Beispiel hier würde mir schon Mal sehr helfen.
Dass ich das ganze meinem Anwendungsfall anpassen muss, ist dann natürlich klar.

Auch das mit dem "Event" verstehe ich nicht so ganz. Was ist das technisch gesehen....?

 

[httpdigest]

Auch das mit dem "Event" verstehe ich nicht so ganz. Was ist das technisch gesehen....?

Was auch immer du unter einem "Event" (zu Deutsch: Ereignis) verstehen willst. Das Absenden einer Bestellung z.B.
Es ist halt einfach ein fachliches Ereignis, dass "irgendetwas" passiert ist. Was auch immer.
Z.B. werden "Webhooks" auch so genannt bei SCM Tools wie einem Git-Server, wenn sie Drittsysteme über Ereignisse benachrichtigen wollen. Ein Ereignis in dieser Domäne könnte z.B. das Pushen in ein Repository sein, um dann per "Webhook" einen Build-Server anzustoßen.

EDIT:
Ich glaube, wichtig zu verstehen ist erstmal: Ein "Event" ist an sich erstmal nichts technisches, also hat mit der technischen Umsetzung eines "Webhooks" nichts zu tun. Es ist etwas fachliches, um ein "Ereignis" zu repräsentieren. Wie du ein Ereignis nun technisch abbildest, unterliegt den Grenzen des darunterliegenden Übertragungsprotokolls wie etwa HTTP.
Im Falle eines HTTP Endpunktes kann die alleinige Existenz des Endpunktes und der Aufruf dessen schon dieses Ereignis bedeuten. Desweiteren kannst du alle HTTP Möglichkeiten verwenden, um das Ereignis weiter zu parametrisieren. Z.B. über den HTTP Path, Query Parameter, den Body, Header (z.B. Cookies). Du musst dich hier wirklich einfach erstmal in HTTP als Protkoll einarbeiten/einlesen. Dann wird auch klar, was du alles mit einem "Webhook" machen kannst.

 

[beta20]

Hallo zusammen,

habe mich nun etwas mehr mit dem Thema befasst.
Das mit dem "Event" ist mir dennoch nicht so ganz klar.

Senderseite
Wenn ich das richtig sehe:
Um meinen User es zu ermöglichen Webhooks zu senden, erstelle ich eine Tabelle "Webhooks":
- ID
- Target_URL
- Event_Type

Hat ein User in meiner App definiert, dass wenn eine Order erstellt wird (event: order_created), dass dann ein Webhook gesendet wird, dann:

- Sende ich via POST einen Request an die TARGET_URL. Da ebenfalls der EventType gespeichert wird, weiß meine App welche Paramater ebenfalls in dem Request übergeben werden müssen (in dem Fall z.B. die Order).
-> Also im Prinzip ein normaler POST Request wird gesendet von meiner Seite.

Stimmt das so?


Empfängerseite:
- Der User hat eine entsprechende Klasse geschrieben, der mein POST Request entgegennimmt.
- Würde der User nur ein Event empfangen können, würde ich es eher verstehen, da ich dann eine Methode habe, der eben die Parameter entgegennimmt.
- Jetzt kommt aber das Event ins Spiel. Ich könnte mir vorstellen, dass der EventType in meinem POST Request als quasi Parameter mitgegeben wird.
- Auf der Empfängerseite empfange ich nun zusätzlich diesen EventType und habe dann nur eine Methode.
- Zunächst prüfe ich den Eventtype ab if(eventType.equals("order_created")
- Wenn dies zutrifft, dann führt der User eben dessen Schritte durch.

Ist das so alles korrekt? Wie gesagt, wie wird der EventType gesendet und empfangen? Hier tue ich mir schwer.

 

[httpdigest]

Alles, was du oben beschreibst, ist ein ganz konkreter Anwendungsfall in einem ganz ganz konkreten Programm, das wir nicht kennen. Nichts davon lässt sich verallgemeinern oder mit "ja, stimmt so" beantworten. Weder brauchst du _immer_ irgendeine Tabelle, noch brauchst du irgendeinen "User".

 

[beta20]

Das mit der Tabelle kann man ignorieren, das war konkret auf meine Applikation. Ebenfalls wird kein User benötigt, das ist korrekt.

Der Rest sollte aber sich verallgemeinern lassen?

 

[mihe7]

Das mit dem "Event" ist mir dennoch nicht so ganz klar.

Ein Event ist einfach die Beschreibung eines in der (ggf. unmittelbar vorangegangenen) Vergangenheit aufgetretenen Ereignisses.

Sende ich via POST einen Request an die TARGET_URL. Da ebenfalls der EventType gespeichert wird, weiß meine App welche Paramater ebenfalls in dem Request übergeben werden müssen (in dem Fall z.B. die Order).

Das ist ein Implementierungsdetail, das für den grundsätzlichen Ablauf unerheblich ist.

Die Anwendung schickt bei Eintritt eines Ereignisses einen Request an eine URL, der eine Beschreibung des Ereignisses enthält. Dabei kann die URL selbst schon einen Teil der Beschreibung beinhalten und (in Abhängigkeit des Ereignisses) ggf. sogar als vollständige Beschreibung ausreichend sein.

Inwiefern und wie Du das ganze für den Anwender konfigurierbar machst, ist eine ganz andere Frage.

Empfängerseite ist ähnlich: ob der User nun eine Klasse schreibt oder einen vorhandenen Dienst nutzt, spielt keine Rolle. Mit einer HTTP-URL wird ein Endpoint eindeutig identifiziert. Es gibt ein System, das diesen Endpoint realisiert, indem es Requests entgegennimmt. Verschiedene Events lassen sich verschieden umsetzen.

Wie gesagt, wie wird der EventType gesendet und empfangen? Hier tue ich mir schwer.

Wenn Du der bestimmende Faktor im Gesamtsystem bist: wie Du willst. Eine Schnittstelle funktioniert ja wie ein Vertrag: alle Parteien verpflichten sich zur Einhaltung des Vertrags.

Wenn Du also sagst, hey Ihr könnt Webhooks über die beta20-API nutzen, dann muss das empfangende System sich daran halten, was Du vorgibst. Willst Dein System dagegen die Ereignisse eines Drittsystems empfangen, wird sich Dein System an die Vorgaben des Drittsystems halten müssen.

 

[beta20]

Ein kleines Beispiel würde mir wie gesagt sehr helfen, insbesondere was den Ereignistyp angeht.

 

[mrBrown]

Ereignistyp

Einfach ein POJO, welchem du entsprechende Bedeutung gibst:

class OrderCreatedEvent {
    String orderId;

    //Constructor/Getter/...
}

Und ein möglicher Jax-RS-Endpunkt dafür:

@Path("webhooks")
interface WebHooks {
   @Path("orders")
   @POST
   public Response orderCreated(OrderCreatedEvent event);
}

 

[beta20]

Ok, danke.

Nochmals 2 Fragen:
a) Wie würde der Request dann aussehen (nicht Endpoint)
b) Wie würde die URL dann aussehen?
c) Habe ich dann pro Event (createOrder, createCustomer etc.) jeweils einen Endpunkt? Oder habe einen Endpunkt und bekomme dann durch das event den Event Typ (createOrder, createCustomer etc) und kann anhand dessen dann die notwendige Dinge tun (if (type == createOrder)// tue das....

Hier ein Beispiel von einer Software, die das anbieten: So würde ich das gerne umsetzen.

Webhooks - billwerk API

 

[mrBrown]

a) Wie würde der Request dann aussehen (nicht Endpoint)
b) Wie würde die URL dann aussehen?

Steht doch beides da?
Ein Post-Request mit der Event-Klasse serialisiert als zB Json an webhooks/orders/.

c) Habe ich dann pro Event (createOrder, createCustomer etc.) jeweils einen Endpunkt? Oder habe einen Endpunkt und bekomme dann durch das event den Event Typ (createOrder, createCustomer etc) und kann anhand dessen dann die notwendige Dinge tun (if (type == createOrder)// tue das....

Beides Möglich. Bleibt dir überlassen.

Hier ein Beispiel von einer Software, die das anbieten: So würde ich das gerne umsetzen.
Webhooks - billwerk API

Da sind doch Beispiele

 

[beta20]

Solangsam verstehe ich das Prinzip:

Sender:
1) Ich habe eine POJO Klasse, in der ich alles speichere, was ich benötige, diese hat zudem einen String eventType;
2) Diese POJO Klasse sende ich als JSON String an eine definierte URL (mein Endpoint)

Endpoint:
1) Endpoint nimmt den JSON String entgegen
2) Ich speichere in einem POJO von der entgegennehmende App die Dinge, die ich benötige bzw. führe weitere Aktionen aus

Stimmt das so?

 

[mihe7]

Stimmt das so?

Ja. Wobei der String eventType nur notwendig ist, wenn Du verschiedene Events über den selben Endpoint abwickelst.

 

[beta20]

Ok, danke.
Könnte ich für eine URL mehrere Endpunkte haben? Wie würde hier der Code dann aussehen? (nach dem Beispiel von oben...)

 

[mrBrown]

Könnte ich für eine URL mehrere Endpunkte haben?

Eine URL ist ein Endpunkt

Wie würde hier der Code dann aussehen? (nach dem Beispiel von oben...)

Wenn du meinst, mehrere Events unter einer Url abzuhandeln:
Einfach alles was mit Order zu tun hat wegnehmen und eventType hinzufügen (da nicht mehr durch den Typ der Klasse gegeben):

class Event {
    String eventType;
    String payload;

    //Constructor/Getter/...
}

@Path("webhooks")
interface WebHooks {
   @POST
   public Response event(Event event);
}

 

[mihe7]

Ich meinte eigentlich andersrum

Der eventType ist in der Klasse nicht notwendig, wenn unter einer URL immer nur eine Art von Ereignis abgewickelt wird.

 

[mrBrown]

Ich meinte eigentlich andersrum

Der eventType ist in der Klasse nicht notwendig, wenn unter einer URL immer nur eine Art von Ereignis abgewickelt wird.

An wen richtet sich das?

 

[mihe7]

1. Zeile als Antwort auf Deinen Kommentar
2. Zeile als Erklärung meines Ansinnens und für @beta20

 

[mrBrown]

Mein Kommentar ist doch grad die Variante mit mehrere Ereignisse unter einer URL, wo eventTyp eben nötig ist?

 

[mihe7]

Hm.. ich dachte sein Kommentar #18 hätte sich auf #17 bezogen. Keine Ahnung

 

[beta20]

Habe hier nochmal eine Frage dazu:
Bspw. meine URL ist: www.mydomain.com/webhhook/ordercreated

Wenn ich das richtig verstehe, definiere ich die URL des Endpoints hier:

@Path("webhooks")
interface WebHooks {
   @POST
   public Response event(Event event);
}

Die Frage für mich ist nun die Übermittlung der Information.
Wie übermittle ich vom Sender zum Empfänger mein Objekt?
Wie muss das programmiertechnisch aussehen?

 

[mihe7]

Du serialisierst Dein Event und schickst es über die Leitung an die Ziel-URL.

Ein Beispiel mit JSON-P dürfte grob wie folgt aussehen (ungetestet, kann Fehler enthalten):

public class Event {
    final String orderId;
    final String customerId;
    public Event(String orderId, String customerId) {
        this.orderId = orderId;
        this.customerId = customerId;
    } 
}

Serverseite:

@Path("webhooks")
@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.APPLICATION_JSON)
public class Webhooks {
    @Path("ordercreated")
    @POST
    public Response orderCreated(JsonObject json) {
        Event event = new Event(json.getString("order-id"), json.getString("customer-id"));
        // mach etwas mit dem event
        return Response.ok();
    }
}

Clientseite:

JsonObject event = Json.createJsonObjectBuilder()
        .add("order-id", orderId)
        .add("customer-id", customerId)
        .build();
    
Client client = ClientBuilder.client();
WebTarget target = client.target("http://www.mydomain.com/webhhook/ordercreated");
Response response = target.request().post(Entity.json(event.toString()));
// behandle response