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 he 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.
HTTP/1.1
POST /billwerk-hook
Host: example.com
Content-Type: application/json
{
"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
ComponentSubscriptionChange
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.