Webhooks

Webhooks provides the option to automatically send real-time notifications when a specific event has happened within the Zero Friction platform for a certain tenant and/or organization. Rather than repeatedly polling for updates, webhooks ensure that relevant information is sent directly to a designated URL.

The Zero Friction webhooks implementation uses signature verification.
Signature verification makes use of the Hash-based Message Authentication Code (HMAC) for authenticating and validating webhooks.

The resulting HMAC, which becomes the signature of the webhook, is then used to authenticate the webhook and validate its payload.
At Zero Friction we use SHA256 signature validation and this signature is sent along in the HTTP header X-Webhook-Signature-256.
We will provide the secret used for the HMAC calculation when requesting access to our webhooks system.

If you want to start using the Zero Friction webhooks system, please contact support@zerofriction.co for more information.

Available webhooks

AdvanceAmountUpdated

Triggered when the advance amount for a contract is updated.

{   
    "_type": "advanceamountupdated",   
    "contractId": "550e8400-e29b-41d4-a716-446655440000",   
    "customerId": "660e8400-e29b-41d4-a716-446655440001" 
}

CollectionCaseClosed

Triggered when a collection case is closed.

{   
    "_type": "collectioncaseclosed",   
    "customerId": "660e8400-e29b-41d4-a716-446655440001",   
    "invoiceIds": [     
          "770e8400-e29b-41d4-a716-446655440002",     
          "880e8400-e29b-41d4-a716-446655440003"   
    ],   
    "collectionCaseId": "990e8400-e29b-41d4-a716-446655440004" 
}

ConsumptionDeleted

Triggered when service consumptions are deleted for a service location within a specific date range.

{   
    "_type": "consumptiondeleted",   
    "serviceLocationId": "aa0e8400-e29b-41d4-a716-446655440005",   
    "rangeStartDateTime": "2024-01-01T00:00:00Z",   
    "rangeEndDateTime": "2024-01-31T23:59:59Z",   
    "externalIdentifier": "CHANNEL-12345",   
    "customerId": "660e8400-e29b-41d4-a716-446655440001",   
    "contractId": "550e8400-e29b-41d4-a716-446655440000" 
}

ConsumptionProcessed

Triggered when service consumptions have finished processing for a service location.

{   
     "_type": "consumptionprocessed",   
     "serviceLocationId": "aa0e8400-e29b-41d4-a716-446655440005",   
     "rangeStartDateTime": "2024-01-01T00:00:00Z",   
     "rangeEndDateTime": "2024-01-31T23:59:59Z",   
     "utilityType": 1,   
     "unitOfMeasure": 1,   
     "externalChannelIdentifier": "CHANNEL-12345",   
     "timeOfUse": "Day" 
}

ContractRemoved

Triggered when a contract is removed from the system.

{   
    "_type": "contractremoved",   
    "contractId": "550e8400-e29b-41d4-a716-446655440000",   
    "customerId": "660e8400-e29b-41d4-a716-446655440001" 
}

ContractServicesUpdated

Triggered when services associated with a contract are updated.

{   
    "_type": "contractservicesupdated",   
    "contractId": "550e8400-e29b-41d4-a716-446655440000",   
    "customerId": "660e8400-e29b-41d4-a716-446655440001",   
    "removedServices": [],   
    "updatedServices": [],   
    "addedServices": [],   
    "removedServiceLocationIds": [] 
}

ContractSigned

Triggered when a contract is signed.

{   
    "_type": "contractsigned",   
    "contractId": "550e8400-e29b-41d4-a716-446655440000",   
    "customerId": "660e8400-e29b-41d4-a716-446655440001" 
}

ContractTerminated

Triggered when a contract is terminated.

{   
    "_type": "contractterminated",   
    "contractId": "550e8400-e29b-41d4-a716-446655440000",   
    "customerId": "660e8400-e29b-41d4-a716-446655440001",   
    "removedServices": [],   
    "removedServiceLocationIds": [] 
}

ContractUpdated

Triggered when contract details are updated, including when the active billing period changes.

{   
    "_type": "contractupdated",   
    "contractId": "550e8400-e29b-41d4-a716-446655440000",   
    "customerId": "660e8400-e29b-41d4-a716-446655440001" 
}

CultureUpdated

Triggered when culture/translation settings are updated at the organization level.

{   
    "_type": "cultureupdated",   
    "countryCulture": "nl-NL",   
    "defaultCulture": "nl-NL",   
    "supportedCultures": ["nl-NL", "en-GB", "fr-FR"] 
}

CustomerCreated

Triggered when a new customer is created.

{   
    "_type": "customercreated",   
    "customerId": "660e8400-e29b-41d4-a716-446655440001" 
}

CustomerDetailsChanged

Triggered when customer details (name, address, etc.) are changed.

{   
    "_type": "customerdetailschanged",   
    "customerId": "660e8400-e29b-41d4-a716-446655440001" 
}

CustomerRemoved

Triggered when a customer is removed from the system.

{   
    "_type": "customerremoved",   
    "customerId": "660e8400-e29b-41d4-a716-446655440001" 
}

EntityAttachmentCreated

Triggered when an entity attachment is created for any entity (customer, contract, invoice, etc.).

{   
    "_type": "entityattachmentcreated",   
    "subjectId": "770e8400-e29b-41d4-a716-446655440002",   
    "entityAttachmentId": "dd0e8400-e29b-41d4-a716-446655440008" 
}

EntityAttachmentDeleted

Triggered when an entity attachment is deleted.

{   
    "_type": "entityattachmentdeleted",   
    "subjectId": "770e8400-e29b-41d4-a716-446655440002",   
    "entityAttachmentId": "dd0e8400-e29b-41d4-a716-446655440008" 
}

EntityAttachmentGroupCreated

Triggered when an entity attachment group is created.

{   
    "_type": "entityattachmentgroupcreated",   
    "subjectId": "770e8400-e29b-41d4-a716-446655440002",   
    "entityAttachmentGroupId": "ee0e8400-e29b-41d4-a716-446655440009" 
}

EntityAttachmentGroupDeleted

Triggered when an entity attachment group is deleted.

{   
    "_type": "entityattachmentgroupdeleted",   
    "subjectId": "770e8400-e29b-41d4-a716-446655440002",   
    "entityAttachmentGroupId": "ee0e8400-e29b-41d4-a716-446655440009" 
}

EntityAttachmentGroupUpdated

Triggered when an entity attachment group is updated (e.g., visibility, validity, approval requirements).

{   
    "_type": "entityattachmentgroupupdated",   
    "subjectId": "770e8400-e29b-41d4-a716-446655440002",   
    "entityAttachmentGroupId": "ee0e8400-e29b-41d4-a716-446655440009" 
}

EntityAttachmentUpdated

Triggered when an entity attachment is updated.

{   
    "_type": "entityattachmentupdated",   
    "subjectId": "770e8400-e29b-41d4-a716-446655440002",   
    "entityAttachmentId": "dd0e8400-e29b-41d4-a716-446655440008" 
}

ExternalDocumentDeliveryFailed

Triggered when external document delivery fails (e.g., email delivery failure).

{   
     "_type": "externaldocumentdeliveryfailed",   
     "entitySubjectId": "770e8400-e29b-41d4-a716-446655440002",   
     "entitySubjectType": 1,   
     "communicationEntryReferenceId": "COMM-12345",   
     "reason": "Email delivery failed: Invalid recipient address" 
}

FeatureFlagsUpdated

Triggered when feature flags are updated at the organization level.

{   
    "_type": "featureflagsupdated",   
    "invoicePaymentStatusEnabled": true 
}

GeneratePaymentLink

Triggered when a payment link needs to be generated for an invoice or collection case.

{   
    "_type": "generatepaymentlink",   
    "referenceId": "770e8400-e29b-41d4-a716-446655440002" 
}

InvoiceAssignedToCollectionCase

Triggered when an invoice is assigned to a collection case.

{   
     "_type": "invoiceassignedtocollectioncase",   
     "customerId": "660e8400-e29b-41d4-a716-446655440001",   
     "invoiceId": "770e8400-e29b-41d4-a716-446655440002",   
     "collectionCaseId": "990e8400-e29b-41d4-a716-446655440004" 
}

InvoiceAvailable

Triggered when an invoice becomes available (status changes to Generated).

{   
     "_type": "invoiceavailable",   
     "customerId": "660e8400-e29b-41d4-a716-446655440001",   
     "invoiceId": "770e8400-e29b-41d4-a716-446655440002" 
}

InvoiceExportRequested

Triggered when an invoice export is manually requested via the API.

{   
     "_type": "invoiceexportrequested",   
     "configuredPluginId": "ff0e8400-e29b-41d4-a716-446655440010",   
     "organisationId": "110e8400-e29b-41d4-a716-446655440011",   
     "queryParams": {     
          "customerId": "660e8400-e29b-41d4-a716-446655440001",     
          "status": "Generated"   
      },   
      "quickFilter": "Overdue",   
      "markAsExported": true 
}

InvoicePaymentDetailsChanged

Triggered when invoice payment details change, including:

  • Payment status changes

  • Payment method changes

  • Payment collection date changes

  • Invoice credited events

{   
     "_type": "invoicepaymentdetailschanged",   
     "customerId": "660e8400-e29b-41d4-a716-446655440001",   
     "invoiceId": "770e8400-e29b-41d4-a716-446655440002" 
}

InvoiceRegenerated

Triggered when an invoice is regenerated.

{   
     "_type": "invoiceregenerated",   
     "customerId": "660e8400-e29b-41d4-a716-446655440001",   
     "invoiceId": "770e8400-e29b-41d4-a716-446655440002" 
}

MailSent

Triggered when an email is successfully sent.

{   
    "_type": "mailsent",   
    "mailId": "MAIL-12345",   
    "referenceId": "770e8400-e29b-41d4-a716-446655440002" 
}

MeterInstalled

Triggered when a meter is installed at a service location.

{   
     "_type": "meterinstalled",   
     "meterId": "120e8400-e29b-41d4-a716-446655440012" 
}

MeterReconfigured

Triggered when a meter is reconfigured (e.g., channel changes, settings updates).

{   
    "_type": "meterreconfigured",   
    "meterId": "120e8400-e29b-41d4-a716-446655440012" 
}

MeterUninstalled

Triggered when a meter is uninstalled from a service location.

{   
    "_type": "meteruninstalled",   
    "meterId": "120e8400-e29b-41d4-a716-446655440012",   
    "oldServiceLocationIds": ["aa0e8400-e29b-41d4-a716-446655440005"] 
}

ProductCreated

Triggered when a new product is created in the system.

{   
    "_type": "productcreated",   
    "productId": "130e8400-e29b-41d4-a716-446655440013" 
}

ProductUpdated

Triggered when product details are updated.

{   
    "_type": "productupdated",   
    "productId": "130e8400-e29b-41d4-a716-446655440013" 
}

ServiceLocationCreated

Triggered when a new service location is created.

{   
    "_type": "servicelocationcreated",   
    "serviceLocationId": "aa0e8400-e29b-41d4-a716-446655440005" 
}

ServiceLocationDeleted

Triggered when a service location is deleted from the system.

{   
    "_type": "servicelocationdeleted",   
    "serviceLocationId": "aa0e8400-e29b-41d4-a716-446655440005" 
}

ServiceLocationUpdated

Triggered when service location details are updated.

{   
    "_type": "servicelocationupdated",   
    "serviceLocationId": "aa0e8400-e29b-41d4-a716-446655440005" 
}

TransactionCreated

Triggered when a billing transaction is created.

{   
    "_type": "transactioncreated",   
    "customerId": "660e8400-e29b-41d4-a716-446655440001",   
    "transactionId": "140e8400-e29b-41d4-a716-446655440014",   
    "transactionReferenceId": "770e8400-e29b-41d4-a716-446655440002",   
    "transactionType": 1 
}


Notes

  • All webhook payloads include a _type discriminator property that identifies the webhook type.

  • Date/time values are in ISO 8601 format (UTC).

  • The HMAC signature in the X-Webhook-Signature-256 header is calculated using the raw JSON body and your provided secret key.