Contract Changed
Sent whenever the state of a contract has changed. There are various reasons why the contract could have changed, e.g.:
contract created
if you only want to be notified about the contract creation then you may also subscribe to
ContractCreated-webhook as this is a subset of contract changed webhook
contract started
The trial has ended
The contract was cancelled
if you only want to be notified about the contract cancellation then you may also subscribe to
ContractCancelled-webhook as this is a subset of contract changed webhook
The contract has ended
The contract was up- or downgraded
a contract phase started / ended
A component subscription was added or changed
a component subscription started or ended
a discount subscription was added or changed
a discount subscription started or ended
a pause was added or changed
a pause has started or ended
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
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.