Use webhooks to integrate proposal, contract (refers to a subscription or a proposal renewal or change) and payment data to your applications.

Summary

In this article, we will go through the steps to set up and test a webhook in your Cacheflow instance. We will also define Cacheflow webhook event types and variables and give examples of each payload.

Implementation

Add a Webhook

Adding a webhook event trigger to your Cacheflow instance is easy! First, navigate to the Webhooks tab from Account > Integrations and Connectors > API. Click on the ellipsis and select “Add a webhook.”

Info needed:
Webhook name
Endpoint URL
Event Type

Enter a name for your webhook and paste in the endpoint URL. Select the desired event type trigger and click Submit.

Testing a webhook

Once the webhook has been added, test it by clicking the “Test” button to the left of the webhook in the list. The test will show the send status below the webhook details.

View webhook events history

View a list of triggered webhook and API events by clicking on the Events tab, next to the Webhooks tab. Easily review event details and confirm that your webhook set up is working as expected.

Event Types

`statement_posted`

Cacheflow will send out a statement_posted webhook event when the billing cycle is complete and an invoice should be issued to a customer.

Payload example:

{  
  "id": "5a954db6-e297-4688-b321-3713407b31ac",  
  "eventType": "statement_posted",  
  "referenceType": "billingschedule",  
  "fields": {  
    "id": "5a954db6-e297-4688-b321-3713407b31ac",  
    "updatedAt": "2024-04-21T16:22:49.601618Z",  
    "contractId": "d92ee834-ec49-43b7-af86-df1d1548c021",  
    "invoiceId": "b0652ad8-020d-46bf-9c6d-9a0a4d4618e5",  
    "invoiceStatus": "open",  
    "invoiceNumber": "INV-1234",  
    "purchaseOrderNumber": "PO-5678",  
    "scheduleDate": "2024-05-21",  
    "issueDate": "2024-05-24",  
    "dueDate": "2024-06-23",  
    "currency": "USD",  
    "totalAmountDue": 1000,  
    "amountWithoutTax": 900,  
    "taxAmount": 100,  
    "balance": 1000  
  }  
}

Variable Name	Type	Description
`contractId`	`UUID`	ID of the subscription in Cacheflow
`invoiceId`	`UUID`	ID of the invoice in Cacheflow
`invoiceStatus`	`InvoiceStatus`	The status of the invoice
`invoiceNumber`	`String`	The invoice number
`purchaseOrderNumber`	`String`	The purchase order number, if available
`scheduleDate`	`LocalDate`	The day when the service period starts. Recurring items are billed at the beginning of the period.
`issueDate`	`LocalDate`	The day the invoice should be sent to the customer
`dueDate`	`String`	The day payment is due
`currency`	`String`	The currency of the amounts
`totalAmountDue`	`Long`	The total amount that should be charged, including usage and tax (if enabled)
`amountWithoutTax`	`Long`	The amount that should be charged without tax
`taxAmount`	`Long`	The amount of tax that should be charged
`balance`	`Long`	The balance of the customer, representing the amount that is due from the customer

`billing_schedule_updated`

Sent when a billingSchedule has been updated with usage data.

Payload example:

{  
  "id": "5b0d09aa-d82d-4ffe-8fc1-202fdb235831",  
  "eventType": "billing_schedule_updated",  
  "referenceType": "billingschedule",  
  "fields": {  
    "id": "5b0d09aa-d82d-4ffe-8fc1-202fdb235831",  
    "updatedAt": "2024-04-21T21:56:45.487244Z",  
    "contractId": "bfaac68f-d6a4-4fd6-9081-2ada19390c54",  
    "amountDue": 0,  
    "currency": "USD"  
  }  
}

Variable Name	Type	Description
`contractId`	`UUID`	ID of the subscription in Cacheflow
`currency`	`String`	The currency of the amounts
`amountDue`	`Long`	The current total amount that should be charged, including any usage charges. Tax is not included.

`proposal_updated`

Sent when a proposal is created or updated by the seller or by a contact that is associated with the proposal.

Payload example:

{  
  "id": "cf2ad997-7c85-4f5c-ab69-aef9e7caf2f8",  
  "eventType": "proposal_updated",  
  "referenceType": "proposal",  
  "fields": {  
    "id": "cf2ad997-7c85-4f5c-ab69-aef9e7caf2f8",  
    "updatedAt": "2024-04-21T22:18:34.904231Z",  
    "name": "Test Proposal",  
    "status": "accepted",  
    "proposalEventType": "updated",  
    "sellerEmail": "[[email protected]](mailto:[email protected]) ",  
    "contact": {  
      "firstName": "Bobby",  
      "lastName": "Jones",  
      "email": "[[email protected]](mailto:[email protected]) "  
    },  
    "customer": {  
      "id": "36a86954-0849-4f5d-8af3-23d159e4b422",  
      "name": "Test Customer"  
    }  
  }  
}

Variable Name	Type	Description
`name`	`String`	Name of the proposal
`status`	`ProposalStatus`	The current status of the proposal
`proposalEventType`	`ProposalEventType`	The type of event that triggered this webhook. See type values below.
`sellerEmail`	`String`	The email of the seller that created the proposal
`contact`	`Contact`	The contact who interacted with the proposal
`customer`	`CustomerSummary`	The customer that the proposal is associated with

ProposalEventType

Value	Associated Actor	Description
`created`	Seller	Proposal created by seller
`updated`	Seller	Proposal updated by seller
`archived`	Seller	Proposal archived by seller
`activated`	Seller	Shared with contact, no signing required
`started`	Seller	Shared with contact when signing required
`set_to_draft`	Seller	Set back to draft by seller
`contact_added`	Seller	Contact added to proposal
`contact_removed`	Seller	Contact removed from proposal
`expired`	Seller	Proposal expired
`cancelled`	Seller	Proposal cancelled by the seller
`deleted`	Seller	Proposal deleted by the seller
`restore`	Seller	Seller restored an archived proposal
`seller_downloaded`	Seller	Seller downloaded the proposal
`buyer_downloaded`	Buyer	Buyer downloaded the proposal
`buyer_printed`	Buyer	Buyer printed the proposal
`viewed`	Buyer	Buyer viewed the proposal
`unviewable_status`	Buyer	Buyer tried to view but proposal is not in a viewable status
`accepted`	Buyer	Buyer accepted the proposal
`invited`	Buyer	Buyer invited another contact to the proposal
`created_signing_doc`	Buyer	Buyer created the signing document
`cancelled_signing_doc`	Buyer	Buyer cancelled the signing document
`signed`	Buyer	Buyer signed the proposal
`buyer_updated`	Buyer	Buyer updated the billing contact or purchase order number
`billing_method_added`	Buyer	Buyer added a new billing method to proposal (for renewal)
`renewal_pending`	Buyer	Buyer accepted the renewal proposal
`approval_requested`	Admin/Approver	Approval for proposal requested
`approval_approved`	Admin/Approver	Proposal approval granted
`approval_rejected`	Admin/Approver	Proposal approval rejected
`approval_canceled`	Admin/Approver	Proposal approval process canceled

`contract_updated`

Sent whenever a contract (subscription) is created, changed, renewed, canceled or ended. An event is also sent if the purchaseOrderNumber is updated.

Payload example:

{  
  "id": "891a4d07-36ea-43f7-81f8-78d75b2daf20",  
  "eventType": "contract_updated",  
  "referenceType": "contract",  
  "fields": {  
    "id": "891a4d07-36ea-43f7-81f8-78d75b2daf20",  
    "name": "Test Contract",  
    "externalId": "external-5678",  
    "contractNumber": "CON-1234",  
    "status": "active",  
    "contractEventType": "created",  
    "customer": {  
      "id": "b32a14f5-b010-424f-9f9f-6f71b989347f",  
      "name": "Test Customer"  
    },  
    "currency": "USD",  
    "totalAmount": 10000,  
    "startDate": "2024-04-21",  
    "endDate": "2025-04-21"  
  }  
}

Variable Name	Type	Description
`name`	`String`	Name of the contract
`externalId`	`String`	The external ID of the contract
`contractNumber`	`String`	The contract number
`status`	`ContractStatus`	The current status of the contract (active, paused, cancelled, ended)
`contractEventType`	`ContractEventType`	The type of event that triggered this webhook. See below for type values.
`customer`	`CustomerSummary`	The customer that the contract is associated with
`currency`	`String`	The currency of the contract
`totalAmount`	`Long`	The total amount of the contract as a result of the contract event
`startDate`	`LocalDate`	The start date of the contract
`endDate`	`LocalDate`	The end date of the contract

ContractEventType

Value	Description
`created`	The contract was initially created.
`billing_added`	Billing information was added to the contract
`billing_updated`	Existing billing information was updated.
`accepted_change`	A change to the contract was accepted.
`accepted_renewal`	A contract renewal was accepted.
`renewal_applied`	A renewal was applied to the contract.
`renewal_due`	The contract is due for renewal.
`canceled`	The contract was canceled.
`updated`	The contract purchaseOrderNumber was updated
`ended`	The contract reached its term end date.

`transfer_completed`

Sent when a transfer is completed either by the payment being processed by an external system or a manual update by the admin.

Payload example:

{  
  "id": "c59fbdcc-2ae2-4107-866e-c81f0ecb81ab",  
  "eventType": "transfer_completed",  
  "referenceType": "transfer",  
  "fields": {  
    "id": "c59fbdcc-2ae2-4107-866e-c81f0ecb81ab",  
    "updatedAt": "2024-04-21T23:38:24.11221Z",  
    "status": "failed",  
    "reason": "over credit limit",  
    "amount": 500,  
    "paidAmount": 0,  
    "currency": "USD",  
    "referenceType": "invoice",  
    "referenceId": "6401ea99-ecc3-4caa-9728-76d2cfc5ba1f",  
    "parentType": "contract",  
    "parentId": "e7e201a6-b3fb-4319-aee6-3813fbba74a1",  
    "customer": {  
      "id": "7f2b738e-5c08-49ff-8e7f-cafc15208832",  
      "name": "Test Customer"  
    }  
  }  
}

Variable Name	Type	Description
`status`	`TransferStatus`	The status of the transfer. See status list below.
`paymentType`	`PaymentType`	The type of payment that was made
`reason`	`String`	The failure reason if the transfer did not succeed
`amount`	`Long`	The total amount the transfer was for
`paidAmount`	`Long`	The amount that was actually paid
`currency`	`String`	The currency of the transfer
`referenceType`	`ReferenceType`	The type of reference the transfer was for, typically the invoice
`referenceId`	`UUID`	The ID of the reference the transfer was for, typically the invoice ID
`parentType`	`ReferenceType`	The type of secondary reference the transfer was for, typically the contract
`parentId`	`UUID`	The ID of the secondary reference the transfer was for, typically the contract ID
`customer`	`CustomerSummary`	The customer that the transfer was for

`TransferStatus`

Status	Description
`pending`	The default status when a transfer is created and should be processed.
`in_progress`	A transfer that has started and is awaiting a response from an external system.
`failed`	The transfer failed (e.g., card declined). Failed transfers will be retried a specified number of times. See more information in this article.
`posted`	The transfer completed successfully.
`canceled`	The transfer is canceled and will no longer be tried.
`declined`	The payment method was declined and will not be retried