Guides
Billwerk+ WebsiteHelp Center ENHelp Center DE

Customers and Contracts

Order Succeeded

Sent when an order was finished successfully. This includes all order types (signup, upgrade, ...).

Typical Scenario

You want to listen to this hook to send an order confirmation by email to the customer.

{
    "ContractId":"6298a006e636b694d807080f",
    "OrderId":"6299046051606668b2b9ef75",
    "CustomerId":"6298a006e636b694d8070809",
    "Event":"OrderSucceeded",
    "EntityId":"62148e3c0c14e1609e9ca5c1"
}

Contract Cancelled

It is sent when the cancellation is triggered, NOT when the contract actually ends. If you want to get notified when a contract ends, use the Contract Changed webhook instead. Usually, a cancellation is triggered sometime before the contract actually ends (notice period).

Typical Scenario

You might want to listen to this hook to get into contact with the customer to make him a special offer if he withdraws his cancellation.

{
    "ContractId":"629479fd471b3f8ab4ad08e0",
    "CustomerId":"6242991221642365b05d86a9",
    "Event":"ContractCancelled",
    "EntityId":"62148e3c0c14e1609e9ca5c1"
}

Contract Changed

Sent whenever the state of a contract has changed. There are various reasons why the contract could have changed, e.g.:

  • The trial has ended
  • The contract has ended
  • The contract was up- or downgraded
  • A component subscription was added or changed

Typical Scenario

You want to listen to this hook to make sure your customers gets what they ordered (and only what they paid for). Together with Contract Created, this is the most important hook. To find out what the current state of the contract is, simply fetch the referenced contract by id and make sure to configure your service to deliver what is configured in the contract.

{
    "ContractId": "645b429bb73d36f442b223df",
    "CustomerId": "645b429bb73d36f442b223db",
    "ExternalCustomerId": "249969",
    "ContractChangeId": "645b42d7f85fee194bce8990",
    "ContractChangeType": "Upgrade",
    "Event": "ContractChanged",
    "EntityId": "63b2d4405b49105c19fa7714"
}

Single event per point in time

For a single point in time, there will be only one webhook sent out containing multiple changes. This is true even if the changes were triggered separately. Examples:

  • Component subscription & a new phase start both on the 1st of the next month; this will trigger only one ContractChanged webhook at this point in time (1st of month at start time), containing both state changes,
  • Trial ends together with two component subscriptions starting at this time - a single ContractChanged webhook is sent, showing the phases & component subscription changes all at once.

Monothonic Order for one Contract

Contract changes for the same contract are monotonically ordered by the timestamp on which the change occurred, and sent out in this monotonic order in terms of one contract.

📘

Important

A monotonic order for multiple contracts can not be guaranteed

ContractCreated webhook is always sent before ContractChanged webhook

Contract change types

  • Signup, Upgrade
  • TrialEndChange
  • ComponentSubscriptionChang
  • DiscountSubscriptionChange
  • Timebased
  • EndContract, Annulation
  • Pause, Resume
  • ExternalSubscriptionSync

As multiple changes can be performed via an order and an order will lead to an Upgrade contract change - it is not enough to rely on a single type like e.g. ComponentSubscriptionChange. The type is intended to be used to opt-out early scenarios.

🚧

Warning

There might be new types and contract changed webhooks added in the future. The implementation must be robust in a way that it is specific about the type of change and does not assume something based on the webhook.

Contract Change Details

All contract change webhooks contain the fields ContractId, ContractChangedType and ContractChangeId. To access more details about what has happened in the contract, call the REST API to get all the details of the contract change.

Contract Created

Sent when a contract was created either via self-service or Admin UI.

ContractCreated is a subset of the ContractChanged. If you have signed up to ContractChanged webhook you do not need to additionally. You can also filter ContractChanged webhooks for a type of Signup.

Typical Scenario

Upon receiving this hook, you'll want to query the billwerk API for the given contract to create a new account in your system and send a welcome email.

To do so, you might also have to fetch the customer whose id is given in the contract.

{
	"ContractId": "6628cec8e87f3692c61de222",
	"CustomerId": "6628cec8e87f3692c61de222",
	"ExternalCustomerId": "e2114548-33f6-4064-869b-2c47f02b222",
	"ContractChangeId": "6628cec8b96fadb67b6b1222",
	"Event": "ContractCreated",
	"EntityId": "5a1d21eee369ee092caef222"
},

Contract Data Changed

Sent whenever data of a contract has changed. This occurs if you execute a PUT/PATCH on a contract, update customfields or the external Id.

Typical Scenario

Upon receiving this hook, you'll want to query the billwerk API for the given contract to create a new account in your system and send a welcome email.

To do so, you might also have to fetch the customer whose id is given in the contract.

{
    "ContractId": "6298a006e636b694d807080f",
    "CustomerId": "6298a006e636b694d8070809",
    "Event": "ContractDataChanged",
    "EntityId": "62148e3c0c14e1609e9ca5c1"
}

Contract Deleted

Sent when a contract was deleted via API or via UI, or when a contract was deleted following deletion of its customer.

Typical Scenario

Upon receving this hook, you can safely proceed to delete the related data on your own systems. As the data is deleted, you cannot request more info on this contract at this stage.

{
"Event" : "ContractDeleted",
"ContractId" : "51d970c8eb596a1168df119a"
}

Contract WrittenOff

Sent, when a write-off is performed (write-off execution). Learn more about the write-off operation from the following article.

📘

Note

You will receive a single webhook for a single contract write-off operation (regardless of number of written-off invoices).

Typical Scenario

Listen to this hook to inform your customer about the state of a written-off contract and the options to resolve the solution.

{
    "ContractId": "629479fd471b3f8ab4ad08e0",
    "CustomerId": "6242991221642365b05d86a9",
    "BookingDate": "2023-05-15",
    "AmountWrittenOff": 61.88,
    "Event": "ContractWrittenOff",
    "EntityId": "62148e3c0c14e1609e9ca5c1"
}

Customer Changed

Sent whenever the base information of a customer has changed because it was modified via the customer portal.

Typical Scenario

Usually, you want to listen to this hook to keep your customer data in sync between your system and billwerk. To do so, fetch the customer by id and apply all necessary changes on your side.

{
    "CustomerId": "62a86d3a826fa0a7d0d07032",
    "Event": "CustomerChanged",
    "EntityId": "62148e3c0c14e1609e9ca5c1"
}

Customer Created

Sent whenever a customer has been created, e.g. through a signup.

Typical Scenario

Usually, you want to listen to this hook to notice new customers on billwerk. After receiving the webhook, fetch the customer by id and create a new customer on your side.

{
    "CustomerId": "62a86b86826fa0a7d0d06b45",
    "Event": "CustomerCreated",
    "EntityId": "62148e3c0c14e1609e9ca5c1"
}

Customer Deleted

Sent whenever the base information of a customer has been deleted.

Typical Scenario

Usually, you want to inform about that customer deleted. To do so, fetch the customer by id and apply all necessary changes on your side.

{
    "CustomerId": "62a86b86826fa0a7d0d06b45",
    "Event": "CustomerDeleted",
    "EntityId": "62148e3c0c14e1609e9ca5c1"
}

Customer Locked

Sent whenever a customer has been locked

Typical Scenario

Usually, you want to inform that the customer is locked. To do so, fetch the customer by id and apply all necessary changes on your side.

{
    "CustomerId": "62a86b86826fa0a7d0d06b45",
    "Event": "CustomerDeleted",
    "EntityId": "62148e3c0c14e1609e9ca5c1"
}

Customer Unlocked

Sent whenever a customer has been unlocked.

Typical Scenario

Usually, you want to inform about that customer unlocked. To do so, fetch the customer by id and apply all necessary changes on your side.

{
    "CustomerId": "6298a006471b3f8ab4b6bfd6",
    "Event": "CustomerUnlocked",
    "EntityId": "62148e3c0c14e1609e9ca5c1"
}

Dunning Created

This webhook is triggered when a new dunning PDF was created and sent/archived.

Typical Scenario

Remark: Not finished yet! You want to listen to this hook to download all individual dunning PDF files.

{
    "Event" : "DunningCreated",
    "DunningId" : "51d97067cb596a1239fff424",
    "CustomerId" : "64ccae03385f8210a5df38d7",
    "ContractID" : "64ccaf64082819a8964eca69",
}

Invoice Created

This webhook is triggered when a new invoice PDF was created and sent/archived.

Typical Scenario

You want to listen to this hook to download all individual invoice PDF files.

{
    "InvoiceId" : "51d97067cb596a1239fff423",
    "ContractId":"621cda87850377beb8e19040",
    "CustomerId":"621cda864076e6f1c77a48e1",
    "Event" : "InvoiceCreated",
    "EntityId":"62148e3c0c14e1609e9ca5c1"
}

Invoice Corrected

This webhook is triggered when a new invoice or credit note PDF was corrected and sent/archived.

Typical Scenario

You want to listen to this hook to fetch a corrected invoice.

{
    "OldInvoiceId":"6298a006d2044479fc05e9f0",
    "NewInvoiceId":"6298c9072c6833903dc32051", //Deprecated. Do not use this anymore
    "NewInvoiceDraftId":"6298c9072c6833903dc32051",
    "OldInvoiceDraftId":"6298a006d2044479fc05e9f0",
    "NewInvoiceDraftIds":["6298c9072c6833903dc32051"],
    "ContractId":"6298a006e636b694d807080f",
    "CustomerId":"6298a006e636b694d8070809",
    "Event":"InvoiceCorrected",
    "EntityId":"62148e3c0c14e1609e9ca5c1"
}

Recurring Billing Approaching

This webhook is triggered when a billing period ended. Depending on your billing delay settings you can use this webhook to pass remaining metered usage or rated items before the actual recurring billing is processed.

Typical Scenario

You want to listen to this hook to pass metered usage or rated itmes before the next recurring billing.

{
    "Event" : "RecurringBillingApproaching",
    "ContractId" : "51d970c8eb596a1168df119a",
}

Updated 8 months ago