Information in a Moneybird account is constantly changing. If you want to perform actions based on these changes, webhooks help you to achieve this. Instead of querying the API at a certain interval, Moneybird will notify you about changes to information in the bookkeeping.

Usage

Webhooks are useful in a broad range of situations. When the state of a sales invoice changes, Moneybird will perform an HTTP request to the URL you provide. Based on the payload of the request, you can determine which action you need to perform.

How it works:

  • You need a URL that Moneybird can call to deliver the payload. The Moneybird servers must be able to access this URL.
  • You can add HTTP basic authentication or other token authentication in the URL, as long as the URL stays valid.
  • Your URL always needs to respond with a 200 HTTP status. Upon registration this is checked.
  • When your URL responds with another HTTP status code, Moneybird will retry to deliver the push 10 times. The time interval between retries is gradually extended.
  • After each push, Moneybird will store the last HTTP status code and HTTP body. Using the webhooks API, you can retrieve this information for debugging purposes.

You can register as many webhooks as required in an administration. Registration is done by sending a POST request to the webhooks API.

We strongly recommend that you use a secure HTTPS endpoint for receiving payload from Moneybird.
If you use unencrypted HTTP, anyone on the network may be able to listen in on sensitive information like contacts and invoices.

Events

It is also possible to subscribe to events. When an event you are subscribed to occurs, Moneybird will perform an HTTP request to the URL you provide. The following events are available:

Event Trigger
contact_changed Contact updated
contact_created Contact created
contact_destroyed A contact has been deleted
contact_merged Contact was merged
credit_invoice_created_from_original Credit note created based on invoice
default_identity_updated Default sender address updated
default_tax_rate_created VAT rate added
direct_bank_link_activated Direct bank link activated
document_attachment_skipped Attachment couldn't be saved from e-mail
document_destroyed Document deleted
document_expired Document expired
document_recurred Recurring document created
document_saved Document saved
document_saved_from_email Document received by email
document_saved_from_endpoint Document received from other Moneybird user
document_saved_from_si Document received via Simplerinvoicing
document_saved_from_upload Document saved
document_style_created Layout added
document_style_destroyed Layout deleted
document_style_updated Layout updated
document_updated Document updated
estimate_accepted_contact Quote accepted online
estimate_billed Quote billed
estimate_created Quote created
estimate_created_from_original Quote created based on the original quote
estimate_destroyed Quote deleted
estimate_mark_accepted Quote marked as accepted
estimate_mark_archived Quote archived
estimate_mark_billed Quote billed
estimate_mark_late Quote marked as expired
estimate_mark_open Quote marked as open
estimate_mark_rejected Quote marked as rejected
estimate_send_email Quote sent by email
estimate_send_manually Quote marked as sent manually
estimate_send_post Quote sent by mail
estimate_send_post_cancelled Quote sent by mail cancelled
estimate_send_post_confirmation Quote sent by mail confirmed by Moneybird
estimate_signed_sender Quote signed by sender
estimate_state_changed_to_late Quote expired
estimate_updated Quote updated
external_sales_invoice_created External sales invoice created
external_sales_invoice_destroyed External sales invoice destroyed
external_sales_invoice_updated External sales invoice updated
external_sales_invoice_state_changed_to_late External sales invoice state changed to late
financial_account_activated Account activated
financial_account_created Account added
financial_account_deactivated Account deactivated
financial_account_destroyed Account deleted
financial_account_renamed Account name changed
financial_statement_created Financial statement added
financial_statement_destroyed Financial statement deleted
financial_statement_updated Financial statement updated
identity_created Sender address added
identity_destroyed Sender address deleted
identity_updated Sender address updated
ledger_account_activated Category activated
ledger_account_booking_created Ledger account booking created
ledger_account_booking_destroyed Link between transaction and category deleted
ledger_account_created Category added
ledger_account_deactivated Category deactivated
ledger_account_destroyed Category deleted
ledger_account_updated Category updated
note_created Note created
note_destroyed Note deleted
payment_destroyed Payment deleted
payment_linked_to_financial_mutation Transaction linked to a financial mutation
payment_registered Payment registered for invoice
payment_send_email Thank You email was sent for payment
payment_transaction_batch_cancelled Payment batch cancelled
payment_transaction_batch_created Payment batch created
recurring_sales_invoice_auto_send_forcefully_disabled The invoice could not be sent automatically, sending automatically is disabled
recurring_sales_invoice_created Recurring invoice created
recurring_sales_invoice_created_from_original Recurring sales invoice created based on original invoice
recurring_sales_invoice_created_from_original_recurring Recurring invoices created based on the original recurring invoice
recurring_sales_invoice_creating_skipped_due_to_limits You have reached the maximum amount of invoices for this month. The recurring invoice is not created.
recurring_sales_invoice_deactivated Recurring invoice deactivated
recurring_sales_invoice_destroyed Recurring invoice deleted
recurring_sales_invoice_invoice_created Sales invoice created
recurring_sales_invoice_started_auto_send Sending automatically enabled
recurring_sales_invoice_stopped_auto_send Sending automatically disabled
recurring_sales_invoice_updated Recurring invoice updated
sales_invoice_created Invoice created
sales_invoice_created_based_on_estimate Invoice created based on quote
sales_invoice_created_based_on_recurring Invoice created based on recurring invoice
sales_invoice_created_from_original Invoice created based on original invoice
sales_invoice_destroyed Invoice deleted
sales_invoice_marked_as_uncollectible Invoice was marked as irrecoverable
sales_invoice_merged Invoice has been merged with another invoice before sending
sales_invoice_merged_with_recurring_sales_invoice Invoice has been merged with other recurring invoices before sending
sales_invoice_paused Processing of invoice has been paused
sales_invoice_send_email Invoice sent by email
sales_invoice_send_manually Invoice manually marked as sent
sales_invoice_send_post Invoice sent by mail
sales_invoice_send_post_confirmation Invoice sent via mail by Moneybird
sales_invoice_send_post_cancelled Sales invoice send by mail has been cancelled
sales_invoice_send_reminder_email Reminder for this sales invoice sent by email
sales_invoice_send_reminder_manually Reminder sent manually
sales_invoice_send_reminder_post Reminder sent by mail
sales_invoice_send_reminder_post_confirmation Invoice reminder sent by mail by Moneybird
sales_invoice_send_si Invoice sent via Simplerinvoicing
sales_invoice_send_si_delivered Received Simplerinvoicing delivery notification
sales_invoice_send_si_error An error occurred while sending via Simplerinvoicing
sales_invoice_send_to_payt Invoice forwarded to Payt
sales_invoice_state_changed_to_draft Invoice state changed to draft
sales_invoice_state_changed_to_late Invoice expired
sales_invoice_state_changed_to_open State of invoice changed to open
sales_invoice_state_changed_to_paid Invoice state changed to paid
sales_invoice_state_changed_to_pending_payment Invoice is pending payment
sales_invoice_state_changed_to_reminded Invoice state changed to reminded
sales_invoice_state_changed_to_scheduled Invoice state changed to scheduled
sales_invoice_unpaused Processing of invoice has been resumed
sales_invoice_updated Invoice updated
send_payment_email Send email after receiving payment
tax_rate_activated Activate VAT rate
tax_rate_created VAT rate added
tax_rate_deactivated VAT rate deactivated
tax_rate_destroyed VAT rate deleted
tax_rate_updated VAT rate updated
todo_completed To-do completed
todo_created To-do added
todo_destroyed To-do destroyed
todo_opened To-do opened
workflow_created Workflow added
workflow_deactivated Workflow deactivated
workflow_destroyed Workflow deleted
workflow_updated Workflow updated
If you decide to not subscribe to any events the old implementation will be used (notifications after state changes of sales invoices). This is to prevent existing webhooks from failing. If you would like to subscribe to a group of events, you can use the top level name of the event (eg. estimate).

Payload

The URL in a webhook will be called by using a `POST` HTTP request. The HTTP body contains a JSON payload with the following structure:

    
      
      Example payload
    
  
{
  "administration_id": "116015326147118082",
  "webhook_id": "116010948233266179",
  "webhook_token": "hPCNhskk1PwGC1pyJZMZmKNT",
  "entity_type": "SalesInvoice",
  "entity_id": "116015245643744263",
  "state": "late",
  "action": "sales_invoice_state_changed_to_late",
  "entity": {
    "id": "116015245643744263",
    "contact_id": "116015245567198212",
    "contact": {
      "id": "116015245567198212",
      "company_name": "Foobar Holding B.V.",
      "firstname": "",
      "lastname": "",
      "attention": "",
      "address1": "Hoofdstraat 12",
      "address2": "",
      "zipcode": "1234AB",
      "city": "Amsterdam",
      "country": "NL",
      "email": "info@example.com",
      "phone": "",
      "send_method": "email",
      "customer_id": "1",
      "tax_number": "",
      "chamber_of_commerce": "",
      "bank_account": "",
      "send_invoices_to_attention": "",
      "send_invoices_to_email": "info@example.com",
      "send_estimates_to_attention": "",
      "send_estimates_to_email": "info@example.com",
      "sepa_active": false,
      "sepa_iban": "",
      "sepa_bic": "",
      "sepa_mandate_id": "",
      "sepa_mandate_date": null,
      "created_at": "2015-02-25T10:39:41.615Z",
      "updated_at": "2015-02-25T10:39:41.615Z",
      "notes": [

      ],
      "custom_fields": [

      ]
    },
    "invoice_id": null,
    "workflow_id": "116015053116802148",
    "document_style_id": "116015053175522406",
    "state": "late",
    "invoice_date": null,
    "payment_conditions": "We verzoeken u vriendelijk het bovenstaande bedrag van {document.total_price} voor {document.due_date} te voldoen op onze bankrekening onder vermelding van het factuurnummer {document.invoice_id}. Voor vragen kunt u contact opnemen per e-mail.",
    "reference": "Project X",
    "language": "nl",
    "currency": "EUR",
    "discount": "0.0",
    "paid_at": null,
    "sent_at": null,
    "created_at": "2015-02-25T10:39:41.685Z",
    "updated_at": "2015-02-25T10:39:41.685Z",
    "details": [
      {
        "id": "116015245648987144",
        "tax_rate_id": "116015052994118749",
        "ledger_account_id": "116015052938544219",
        "amount": "1 x",
        "description": "Project X",
        "price": "300.0",
        "row_order": 1,
        "total_price_excl_tax_with_discount": "300.0",
        "total_price_excl_tax_with_discount_base": "300.0",
        "tax_report_reference": [
          "NL/1a"
        ],
        "created_at": "2015-02-25T10:39:41.693Z",
        "updated_at": "2015-02-25T10:39:41.693Z"
      }
    ],
    "payments": [

    ],
    "custom_fields": [

    ],
    "notes": [

    ],
    "attachments": [

    ]
  }
}

The entity attribute contains a representation of the entity equal to the JSON representation you get when requesting the entity using the API. The state attribute contains the new state of the entity that triggered the push. Notice that the state in the push and the state in the entity can differ. The state of the entity could have changed in the meantime and always contains the current state in the database. The action attribute contains the name of the event that triggered the push.