Webhooks

webhook.get

Request for the details of the webhooks registered for the account


NO FILTER AVAILABLE

Sample request

{
    "SERVICE": "webhook.get"
}

RESPONSE (List of Registered webhooks)
Tags Description
WEBHOOK_ID ID of the webhook
ENDPOINT Address of the webhook endpoint
TYPE Type of endpoint webhook
EVENTS Events registered to the endpoint

Sample response

{
  "REQUEST": {
    "SERVICE": "webhook.get"
  },
  "RESPONSE": {
    "WEBHOOKS": [
      {
        "WEBHOOK_ID": "15",
        "ENDPOINT": "http://endpoint/url",
        "TYPE": "url",
        "EVENTS": "customer.created,customer.updated"
      },
      {
        "WEBHOOK_ID": "16",
        "ENDPOINT": "http://endpoint2/url",
        "TYPE": "url",
        "EVENTS": "invoice.created,invoice.completed,estimate.created,estimate.updated"
      }
    ]
  }
}

webhook.create

Request for registering a webhook


DATA
Tags Description
TYPE Type of endpoint: "url" | "email". (Only "url" is currently available)
ENDPOINT Address of the endpoint with a valid URL or email format.
EVENTS Comma separated values of the events to attach to the endpoint:
customer.created
customer.updated
customer.deleted
invoice.created
invoice.completed
invoice.canceled
estimate.created
estimate.updated
contact.created
contact.updated
contact.deleted
cancellation.created
cancellation.canceled

Sample request

{
 "SERVICE":"webhook.create",
 "DATA": {
    "TYPE": "url",
    "ENDPOINT": "http://endpoint/url",
    "EVENTS": "customer.created,customer.updated"
  }
}

RESPONSE
Tags Description
STATUS Status of the request.
WEBHOOK_ID ID of the created webhook.

Sample response

{
    "REQUEST": {
        "SERVICE": "webhook.create",
        "DATA": {
            "TYPE": "url",
            "ENDPOINT": "http://endpoint/url",
            "EVENTS": "customer.created,customer.updated"
        }
    },
    "RESPONSE": {
        "STATUS": "success",
        "WEBHOOK_ID": 15
    }
}

webhook.delete

Request for deleting a webhook registration


DATA
Tags Description
WEBHOOK_ID ID of the webhook to delete.

Sample request

{
  "SERVICE": "webhook.delete",
  "DATA": {
    "WEBHOOK_ID": "15"
  }
}

RESPONSE (List of Registered webhooks)
Tags Description
STATUS Status of the request.

Sample response

{
    "REQUEST": {
        "SERVICE": "webhook.delete",
        "DATA": {
            "WEBHOOK_ID": "15"
        }
    },
    "RESPONSE": {
        "STATUS": "success"
    }
}

Notifications

The objects pushed to the endpoints in are in JSON format. They have the following information:

id : Notification ID for historical use
type : Name of the event that triggered the notification
Objects : "customer" , "contact" , "invoice" , "estimate" objects and their details
created : Timestamp of the notification


Structure of the Notification Objects

The objects are not assembled separately. FastBill calls the matching read action internally and passes on its response, with the keys converted to lower case — at the top level and one level deep in lists such as items, vat_items and payments.

An object in the payload therefore contains exactly the same fields as the corresponding read action:

EventObjects in the payload
customer.created
customer.updated
customer.deleted		customer — see customer.get
contact.created
contact.updated
contact.deleted		contact — see contact.get
invoice.created
invoice.completed
invoice.canceled		invoice — see invoice.get
customer — see customer.get
cancellation.created
cancellation.canceled		same as the invoice events; the cancellation invoice is in invoice
estimate.created
estimate.updated		estimate — see estimate.get
customer — see customer.get

We deliberately no longer keep a separate field list here: it would be a copy that ages against the read actions.

Sample notification for invoice.created

{
  "id": 11,
  "type": "invoice.created",
  "created": "2016-03-02 17:37:13",
  "invoice": {
    "invoice_id": "14566",
    "type": "outgoing",
    "customer_id": "2",
    "customer_number": "2",
    "customer_costcenter_id": "0",
    "project_id": "0",
    "currency_code": "EUR",
    "delivery_date": "Leistungszeitraum entspricht Rechnungsdatum.",
    "invoice_title": "One more time",
    "cash_discount_percent": "0.00",
    "cash_discount_days": "0",
    "sub_total": 80,
    "vat_total": 15.2,
    "vat_items": [
      {
        "vat_percent": "19.00",
        "complete_net": 80,
        "vat_value": 15.2
      }
    ],
    "items": [
      {
        "invoice_item_id": "18",
        "article_number": "",
        "description": "Produkt",
        "quantity": "1.0000",
        "unit_price": "80.00000000",
        "vat_percent": "19.00",
        "vat_value": 15.2,
        "complete_net": 80,
        "complete_gross": 95.2,
        "sort_order": 1
      }
    ],
    "total": 95.2,
    "organization": "",
    "note": "",
    "salutation": "",
    "first_name": "John",
    "last_name": "Mustemann",
    "address": "Inheidener str. 12",
    "address_2": "",
    "zipcode": "",
    "city": "Frankfurt",
    "payment_type": "1",
    "bank_name": "",
    "bank_account_number": "",
    "bank_code": "",
    "bank_account_owner": "",
    "bank_iban": "",
    "bank_bic": "",
    "country_code": "DE",
    "vat_id": "",
    "template_id": "1",
    "invoice_number": "7",
    "introtext": "wir erlauben uns f\u00fcr unsere Bem\u00fchungen folgende Positionen in Rechnung zu stellen.",
    "paid_date": "0000-00-00 00:00:00",
    "is_canceled": "0",
    "invoice_date": "2016-03-02",
    "due_date": "2016-03-16 00:00:00",
    "payment_info": "",
    "lastupdate": "2016-03-02 18:37:10",
    "document_url": "http:\/\/mydev.fastbill.com\/download\/iGNwBuGMEknEXll.9k-1oOgskmlsdmvshdu"
  },
  "customer": {
    "customer_id": "2",
    "customer_number": "2",
    "days_for_payment": "14",
    "created": "2016-03-02 15:26:57",
    "payment_type": "1",
    "bank_name": "",
    "bank_account_number": "",
    "bank_code": "",
    "bank_account_owner": "",
    "bank_iban": "",
    "bank_bic": "",
    "bank_account_mandate_reference": "",
    "show_payment_notice": "1",
    "account_receivable": "",
    "customer_type": "consumer",
    "top": "0",
    "newsletter_optin": "1",
    "organization": "",
    "position": "",
    "salutation": "",
    "first_name": "John",
    "last_name": "Mustermann",
    "address": "Inheidener str. 12",
    "address_2": "",
    "zipcode": "",
    "city": "Frankfurt",
    "country_code": "DE",
    "secondary_address": "",
    "phone": "",
    "phone_2": "",
    "fax": "",
    "mobile": "",
    "email": "",
    "vat_id": "",
    "currency_code": "EUR",
    "lastupdate": "2016-03-02 15:58:04",
    "tags": ""
  }
}
support@fastbill.com
© 2021 FastBill GmbH