Revenue Webhook Contract

Purpose

The client will implement and provide an HTTP POST webhook URL. ICMA Professional Services will store the supplied URL and use it for all subsequent revenue pushes to the client.

Integration flow

  1. The client implements an HTTP POST webhook endpoint.
  2. The client provides the webhook URL to ICMA Professional Services. .
  3. ICMA Professional Services stores the URL against the client's provider configuration.
  4. For each subsequent revenue push, ICMA sends the request payload in Section 3 to the saved URL.
  5. The client's webhook processes the request and returns the response payload in Section 4.

Request sent to the client's webhook

Method: GET
Content-Type: application/json 

{
    public string MerchantCode { get; set; }
    public string? RevenueCode { get; set; } 
    public string? RevenueName { get; set; } 
    public string AgencyCode { get; set; } 
    public string AgencyName { get; set; } 
    public bool IsRevenue { get; set; } 
}
Field Type Description
MerchantCode String DTSS
RevenueCode String? Required when IsRevenue is true; otherwise, null.
RevenueName String? Required when IsRevenue is true; otherwise, null.
AgencyCode String Required agency code.
AgencyName String Required agency name.
IsRevenue Bool Indicates whether the payload represents revenue.

Conditional requirement: AgencyCode and AgencyName are always available. When IsRevenue is true, RevenueCode and RevenueName are available. When IsRevenue is false, RevenueCode and RevenueName will be null.

Response expected from the client's webhook 

public class SendRevenueToProviderResponseDto 
{
public string Message { get; set; } 
public bool IsSuccessful { get; set; } 
}
Field Type Description
Message string Human-readable description of the processing result.
IsSuccessful bool True when the request was processed successfully; otherwise false.

JSON examples

Revenue request 

{
    "merchantCode": "DTSS",
    "revenueCode": "REV-001", 
    "revenueName": "Business Premises Levy", 
    "agencyCode": "AGY-025", 
    "agencyName": "Example Revenue Agency", 
    "isRevenue": true 
}

Response 

{
    "message": "Record received and saved successfully.", 
    "isSuccessful": true 
}

Webhook URL submission: The client should provide the final reachable webhook URL to ICMA Professional Services for registration before revenue pushes commence.