Skip to main content

Welcome to our Dev Docs!

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.

POST /billwerk-hook
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.


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.