Webhooks
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></invoice> <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>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.updateResponse 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.