Webhooks

With webhooks you can be informed about certain events.
If a previously defined event occurs, Billomat sends a POST request to the stored URL. The affected object is delivered there.
In case of success the requested URL must respond with the HTTP status code between 200 and 299. Different status codes are interpreted as errors.

Events

In Billomat you can store up to one URL for various events under “Settings > Webhooks”. Also the format (XML or JSON) can be set and a combination of user name and password could be entered if the called URL is password protected.

Webhook request

When the event occurs Billomat sends a 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 & 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>project 123</label>
    <intro>We are pleased to offer you the following items into account:</intro>
    <note>Thank you for your order!</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

Order

If an event triggers other events (example: the creation of a payment causes the creation of a comment and the invoice is marked as paid), the order of webhook requests is indeterminate. However, each request has the header field X-Billomat-Webhook-Request-ID. With this, the requests can be sorted chronologically.

Event

With the header X-Billomat-Webhook-Event the event that triggered the Webhook request is specified. This header may have the following values:

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

Response and behavior in case of error

The requested URL must respond within 10 seconds and must provide the HTTP status code 2xx returned in case of success. All other status codes are interpreted as errors. Forwarding with the status code 30x is not possible.
In case of failure with a HTTP status code other than 410 the request is retried after a minute. If the the second call still fails, Billomat retries another request after a further hour and after another six hours.
If all calls fail, the webhook is disabled and an e-mail informs the account owner.
All requests from the same event are send in the order of their occurrence. So, for example, if several invoices are created the webhook requests are fired in the order of creation. If a request fails permanently all subsequent requests are not sent.