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.

Idempotency

Webhook push requests include an `Idempotency-Key` header. This value is unique for each individual webhook push. Since Moneybird retries a push if a non-200 status code is received, you can use this value to ensure that your backend never processes the same push twice.

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
administration_activated Administration activated
administration_added Administration added
administration_cancelled Removal of administration requested
administration_changed Administration updated
administration_deleted Removal of administration requested
administration_reactivated Administration reactivated
administration_removed Administration deleted
administration_suspended Administration suspended
administration_automatic_bookers_activated Activated automatic linking of transactions
administration_automatic_bookers_deactivated Deactivated automatic linking of transactions
administration_data_analysis_permission_unset Data analysis permission withdrawn
administration_data_analysis_permission_set Data analysis permission given
administration_details_edited Administration changed
administration_moneybird_payments_activated Moneybird Payments activated
administration_payments_without_proof_activated Activated payments without proof
administration_payments_without_proof_deactivated Deactivated payments without proof
administration_update_period_locked_until Locked period updated
adviser_updated Adviser updated
adviser_created Adviser created
adviser_deleted Adviser deleted
adviser_updated_photo Profile image added
adviser_email_concept_state_sent E-mail about concept state sent
adviser_email_published_state_sent E-mail about published state sent
adviser_experience_created Experience created
adviser_experience_updated Experience updated
adviser_experience_deleted Experience deleted
adviser_education_created Education created
adviser_education_updated Education updated
adviser_education_deleted Education deleted
adviser_company_created Company created
adviser_company_updated Company updated
adviser_company_photo Company image added
adviser_company_location_created Location created
adviser_company_location_deleted Location deleted
advisers_location_created Location created
advisers_location_deleted Location deleted
adyen_payment_instrument_created Moneybird card created
adyen_payment_instrument_updated Moneybird card updated
booking_rule_created Booking rule created
booking_rule_updated Booking rule updated
booking_rule_destroyed Booking rule deleted
contact_archived Contact archived
contact_activated Contact activated
contact_changed Contact updated
contact_created Contact created
contact_created_from_checkout_order Contact created through checkout
contact_destroyed Contact deleted
contact_mandate_request_failed Mandate request failed
contact_mandate_request_initiated Mandate request sent
contact_mandate_request_succeeded Mandate request succeeded
contact_merged Contact was merged
contact_person_created Contact person created
contact_person_destroyed Contact person deleted
contact_person_updated Contact person updated
credit_invoice_created_from_original Credit note created based on invoice
default_identity_updated Default sender address updated
default_tax_rate_created Default VAT rate added
direct_bank_link_activated Bank link activated
direct_debit_transaction_created Direct debit batch created
direct_debit_transaction_deleted Direct debit batch deleted
document_attachment_skipped Attachment couldn't be saved from email
document_created_from_original Document created based on an original document
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_si Document received via Peppol
document_style_created Layout added
document_style_destroyed Layout deleted
document_style_updated Layout updated
document_updated Document updated
email_domain_deactivated Sending from your own domain has been disabled.
email_domain_validated Your domain is verified.
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 to %{address}
estimate_send_post_cancelled Sending by mail cancelled
estimate_send_post_confirmation Sent by mail by Moneybird
estimate_signed_sender Quote signed by sender
estimate_state_changed_to_late Quote has expired
estimate_updated Quote updated
external_sales_invoice_created External invoice created
external_sales_invoice_destroyed External invoice deleted
external_sales_invoice_marked_as_dubious Marked external invoice as dubious
external_sales_invoice_marked_as_uncollectible External invoice marked as uncollectible
external_sales_invoice_updated External invoice updated
external_sales_invoice_state_changed_to_late External invoice has expired
external_sales_invoice_state_changed_to_open State of external invoice changed to open
external_sales_invoice_state_changed_to_paid External invoice has been paid
external_sales_invoice_state_changed_to_uncollectible External invoice changed to uncollectible
feature_preference_opt_in Beta feature turned on
feature_preference_opt_out Beta feature turned off
feed_entry_snoozed Feed entry snoozed
feed_entry_unsnoozed Feed entry unsnoozed
financial_account_activated Account activated
financial_account_created Account added
financial_account_deactivated Account deactivated
financial_account_destroyed Account deleted
financial_account_bank_link_created Bank link created
financial_account_bank_link_destroyed Bank link removed
financial_account_bank_link_updated Bank link updated
financial_account_renamed Account name changed
financial_statement_created Financial statement added
financial_statement_destroyed Financial statement deleted
financial_statement_updated Financial statement updated
goal_completed Goal completed
goal_uncompleted Goal not completed
identity_created Sender address added
identity_destroyed Sender address deleted
identity_updated Sender address updated
ledger_account_activated Category activated
ledger_account_booking_created Transaction booked on category
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
mollie_credential_created Link with Mollie created
mollie_credential_destroyed Link with Mollie removed
note_created Note created
note_destroyed Note deleted
order_created Order placed
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_method_edited Payment method updated
payment_transaction_authorized Direct debit transaction approved by bank
payment_transaction_awaiting_authorization Direct debit transaction waiting for approval by bank
payment_transaction_batch_cancelled Payment batch cancelled
payment_transaction_batch_created Payment batch created
payment_transaction_executing Direct debit transaction being executing
payment_transaction_paid Direct debit transaction accepted
payment_transaction_pending Direct debit transaction pending
payment_transaction_rejected Direct debit transaction rejected
payment_transaction_technically_validated Direct debit payment is technically approved by the bank
ponto_connected Ponto is connected
ponto_disconnected Ponto connection deleted
ponto_direct_bank_link_activated Ponto bank link activated
ponto_direct_bank_link_expired Ponto bank link expired
product_activated Product activated
product_created Product created
product_deactivated Product deactivated
product_destroyed Product deleted
product_updated Product updated
project_activated Project activated
project_created Project added
project_archived Project deactivated
project_destroyed Project deleted
project_updated Project updated
purchase_transaction_added_to_batch Transaction added to credit transfer batch
purchase_transaction_authorized Payment authorized at bank
purchase_transaction_awaiting_authorization Payment awaiting authorization at bank
purchase_transaction_batch_cancelled Credit transfer batch cancelled
purchase_transaction_batch_created Purchase transaction batch created
purchase_transaction_created Transaction created
purchase_transaction_deleted Transaction deleted
purchase_transaction_executing Payment in execution
purchase_transaction_paid Payment succeeded
purchase_transaction_pending Payment pending
purchase_transaction_rejected Payment rejected
purchase_transaction_technically_validated Payment technically approved by the bank
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_based_on_subscription Invoice created based on subscription
sales_invoice_created_from_checkout_order Sales invoice created through checkout
sales_invoice_created_from_original Invoice created based on original invoice
sales_invoice_destroyed Invoice deleted
sales_invoice_marked_as_dubious Invoice marked as dubious
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_revert_dubious Revert marking as dubious
sales_invoice_revert_uncollectible Invoice marked as uncollectible
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 Sending by mail 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 Peppol
sales_invoice_send_si_delivered Received Peppol delivery notification
sales_invoice_send_si_error An error occurred while sending via Peppol
sales_invoice_send_to_payt Invoice forwarded to Online incasso
sales_invoice_state_changed_to_draft Invoice state changed to draft
sales_invoice_state_changed_to_late Invoice has expired
sales_invoice_state_changed_to_open State of invoice changed to open
sales_invoice_state_changed_to_paid Invoice has been 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_state_changed_to_uncollectible Invoice state changed to uncollectible
sales_invoice_unpaused Processing of invoice has been resumed
sales_invoice_updated Invoice updated
send_payment_email Payment notification email sent
send_payment_unsuccessful_email Email after a failed payment sent
subgoal_assigned Step assigned
subgoal_completed Step completed
subgoal_uncompleted Step not completed
subscription_cancelled Subscription cancelled
subscription_created Subscription created
subscription_destroyed Subscription deleted
subscription_edited Plan changed
subscription_updated Subscription updated
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
time_entry_created Time entry created
time_entry_destroyed Time entry destroyed
time_entry_sales_invoice_created Time entry invoiced
time_entry_updated Time entry updated
todo_completed To-do completed
todo_created To-do added
todo_destroyed To-do deleted
todo_opened To-do viewed
ultimate_benificial_owner_created Ultimate beneficial owner created
ultimate_benificial_owner_updated Ultimate beneficial owner updated
user_invited User invited
user_invited_for_call User invited for a call
user_removed User deleted
vat_return_created VAT-return filed
vat_return_received VAT-return is received by the tax authorities
vat_return_paid VAT-return paid
vat_suppletion_created Digital VAT suppletion submitted
vat_suppletion_received Electronic vat-suppletion is received by the tax authority
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.