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; Co. KG
Hollertszug 26&
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.