Webhooks
Webhooks
Mit Webhooks kann man sich über bestimmte Ereignisse informieren lassen.
Tritt ein zuvor festgelegtes Ereignis ein, sendet Billomat einen POST-Request an eine hinterlegte URL. Der betroffene Datensatz wird dabei mitgeliefert.
Die aufgerufene URL muss im Erfolgsfall mit dem HTTP-Statuscode zwischen 200 und 299 antworten. Abweichende Status-Codes werden als Fehler interpretiert.
Ereignisse
In Billomat kann unter „Einstellungen > Webhooks“ für diverse Ereignisse maximal eine URL hinterlegt werden. Hier kann auch das Format (XML oder JSON) festgelegt werden und bei Bedarf eine Kombination von Nutzernamen und Passwort angegeben werden, falls die aufzurufende URL passwortgeschützt ist.
Webhook-Aufruf
Tritt das Ereignis ein, schickt Billomat einen POST-Request.
Content-Type: application/xml Accept-Encoding: gzip, deflate Host: example.com Connection: close Content-Length: 1060 User-Agent: Billomat-Webhook X-Billomat-Webhook-Id: 1 X-Billomat-Webhook-Request-Id: 510 X-Billomat-Webhook-Event: invoice.create
<?xml version="1.0" encoding="UTF-8"?>
<invoice>
<id type="integer">1</id>
<client_id type="integer">123</client_id>
<contact_id type="integer"></contact_id>
<created type="datetime">2007-12-13T12:12:00+01:00</created>
<invoice_number>RE123</invoice_number>
<number type="integer">123</number>
<number_pre>RE</number_pre>
<status>OPEN</status>
<date type="date">2009-10-14</date>
<supply_date>2009-10-12</supply_date>
<supply_date_type>SUPPLY_DATE</supply_date_type>
<due_date type="date">2009-10-24</due_date>
<due_days type="integer">10</due_days>
<address>Billomat GmbH &amp;amp; Co. KG
Hollertszug 26&amp;
57562 Herdorf
Deutschland</address> <discount_rate type="float">2.0</discount_rate>
<discount_date type="date">2009-10-21</discount_date>
<discount_days type="integer">7</discount_days>
<discount_amount type="float">2.0</discount_amount>
<label>Projekt 123</label>
<intro>Wir freuen uns, Ihnen folgende Positionen in Rechnung stellen zu drüfen:</intro>
<note>Vielen Dank für Ihren Auftrag!</note>
<total_gross type="float">107.1</total_gross>
<total_net type="float">90.0</total_net>
<net_gross>NET</net_gross>
<reduction>10</reduction>
<total_gross_unreduced type="float">119.0</total_gross_unreduced>
<total_net_unreduced type="float">100.0</total_net_unreduced>
<paid_amount type="float">20.0</paid_amount>
<open_amount type="float">99.0</open_amount>
<currency_code>EUR</currency_code>
<quote type="float">1.0000</quote>
<offer_id></offer_id>
<confirmation_id>7</confirmation_id>
<recurring_id></recurring_id>
<taxes type="array">
<tax>
<name>MwSt</name>
<rate type="float">19.0</rate>
<amount type="float">19.0</amount>
</tax>
</taxes>
<payment_types>CASH,BANK_TRANSFER,PAYPAL</payment_types>
</invoice>
HTTP-Header
Reihenfolge
Werden durch ein Ereignis weitere Ereignisse ausgelöst (Beispiel: Das Verbuchen einer Zahlung sorgt dafür, dass ein Kommentar geschrieben und die Rechnung als bezahlt markiert wird), ist die Reihenfolge der Webhook-Requests unbestimmt. Jeder Request besitzt aber das Header-Feld X-Billomat-Webhook-Request-Id. Hiermit können die Requests chronologisch sortiert werden.
Ereignis
Mit dem Header X-Billomat-Webhook-Event wird das Event angegeben, das den Webhook-Request ausgelöst hat. Möglich sind folgende Werte:
invoice.create invoice.update invoice.status invoice.send invoice.delete invoice_comment.create invoice_comment.delete invoice_payment.create invoice_payment.delete recurring.create recurring.update recurring.delete offer.create offer.update offer.status offer.send offer.delete offer_comment.create offer_comment.delete confirmation.create confirmation.update confirmation.status confirmation.send confirmation.delete confirmation_comment.create confirmation_comment.delete reminder.create reminder.update reminder.status reminder.send reminder.delete credit_note.create credit_note.update credit_note.status credit_note.send credit_note.delete credit_note_comment.create credit_note_comment.delete credit_note_payment.create credit_note_payment.delete delivery_note.create delivery_note.update delivery_note.status delivery_note.send delivery_note.delete delivery_note_comment.create delivery_note_comment.delete article.create article.update article.delete article_property.create article_property.update article_property.delete article_property_value.update client.create client.update client.delete client_property.create client_property.update client_property.delete client_property_value.update contact.create contact.update contact.delete incoming.create incoming.update incoming.status incoming.delete incoming_comment.create incoming_comment.delete incoming_payment.create incoming_payment.delete incoming_property.create incoming_property.update incoming_property.delete incoming_property_value.update supplier.create supplier.update supplier.delete supplier_property.create supplier_property.update supplier_property.delete supplier_property_value.update
Antwort und Verhalten im Fehlerfall
Die aufgerufene URL muss innerhalb von 10 Sekunden antworten und im Erfolgsfall den HTTP-Statuscode 2xx zurück liefern. Alle anderen Statuscodes werden als Fehler interpretiert. Eine Weiterleitung mit den Statuscodes 30x ist nicht möglich.
Im Fehlerfall wird bei einem HTTP-Status ungleich 410 der Aufruf nach einer Minute erneut versucht. Schlägt auch der zweite Aufruf fehl, werden erneute Versuche nach einer weiteren Stunde und nach weiteren 6 Stunden unternommen.
Schlagen alle Aufrufe fehl, wird der Webhook deaktiviert und der Account-Inhaber per E-Mail darüber informiert.
Alle Requests des selben Ereignisses werden in der Reihenfolge ihres Eintretens abgesetzt. Werden also beispielsweise mehrere Rechnungen erzeugt, werden die Webhook-Requests in der Reihenfolge der Erzeugung gefeuert. Schlägt ein Aufruf dauerhaft fehl, werden auch Folge-Requests nicht gesendet.