Introduction to Webhooks

The Ansira Application generates events when certain actions happen, for example, when a claim is created or an order is placed. You can listen to and group these events using webhooks to automate actions in your own systems, for example, creating a new support ticket, sending an email, or calling our APIs to gather additional information.

How It Works

There are two ways an application can verify the status of a request to a third-party system: polling and webhooks. While polling forces applications to continually ask for the status of a request, webhooks allow the application to get a notification when the desired event happens.

In Layman’s terms, polling is like calling your doctor’s office every hour of the day to check if your test results are ready. A webhook is like having the office contact you when the test results are ready.

Webhooks is a Developer Portal self-service module available to authorized users. It allows you to select events that should be sent within the same channel by grouping them together in one webhook.

List Webhooks

List all webhook subscriptions.

The Webhooks main view shows a list of the Webhooks created with the most important information of each one.

You can apply filters to the list, by Webhook Name, TP Webhook ID, Event Subscribed, Target URL and Status.

Create a New Webhook

Add and Register Webhook Subscriptions in the System.

1) On the Webhooks home page, click on Add a Webhook.

2) In the subsequent form you will need to enter the following information:

Name: A friendly name that will allow you to easily organize, recognize and search for Webhooks within the Ansira Application

TP Webhook ID: A unique external identifier that can be used to perform API operations.

Signature Secret: The secret that will be used by the external system to confirm that the data sent to the Target URL is coming from Ansira. Note: To validate the signature, the external system must follow the development guidelines related to how the signature is calculated.

Target URL: The URL that will receive the notification when one of the registered events happened. This URL must be secure (HTTPS).

Webhook Events: The events that will trigger the notification from the Ansira application. Keep in mind that all events will be processed individually. URL OpenAPI file: here

Status:Whether the Webhook is active or not. When a webhook is paused, the target URL will no longer be notified when any of the registered events occur.

Broadcast Supported Events

This is a list of all the types of events we currently send. We may add more at any time, so in developing and maintaining your code, you should not assume that only these types exist.

3) Once the Webhook is created, it will be displayed in the main view where all the client's Webhooks are listed.

Events Payload example

Event Fund Transaction Payload example

{
"specversion": "1.0",
"id": "7ad7753c-150f-54cf-9afc-2d47b0eb0715",
"source": "urn:sproutloud:broadcasts",
"type": "sproutloud.funds.fund.returned.v1",
"datacontenttype": "application/json",
"time": "2022-11-30T00:50:41Z",
"data": {
"tp_fund_id": "22110000404088",
"currency_code": "USD",
"amount": "18.93",
"tp_transaction_id": null,
"budget_id": "BU01010000000000",
"reference_id": "CA22110000613281",
"fund_id": "FU22110000404088",
"fund_name": "SL funds to test",
"expiration_date": null,
"fund_tags": null,
"account_id": "AC19070000001449",
"master_account_id": "AC01010000000000"
}
}

Event Order Payload example

{
"specversion": "1.0",
"id": "5c7dd225-50af-56e7-86b3-38b5d5f2f7db",
"source": "urn:sproutloud:broadcasts",
"type": "sproutloud.orders.order.submitted.v1",
"datacontenttype": "application/json",
"time": "2022-11-30T00:29:16Z",
"data": {
"reference_id": "CA22110000613281",
"order_name": "Call tracking vehicle - 29th Nov 2022 (6)",
"status": "OK",
"account_id": AC19070000001449,
"master_account_id": "AC19060000131922",
"order_contact_id": "CN19070000001450",
"tp_po_number": "null",
"order_submit_date": "2022-11-30T00:29:19Z",
"order_approval_ts": null,
"billing_option": null,
"billing_unit": "null",
"order_type": "Vehicle Graphics Custom"
}
}

Event Campaign Payload example

{
"specversion": "1.0",
"id": "f98be6e6-0c2a-5eda-97a1-e024d2195e5b",
"source": "urn:sproutloud:broadcasts",
"type": "sproutloud.campaigns.campaign.processed.v1",
"datacontenttype": "application/json",
"time": "2022-11-30T04:47:11Z",
"data": {
"reference_id": "CA22110000558195",
"campaign_name": "11x6 GM MD test profile - 18th Nov 2022",
"status": "PROCESSING",
"campaign_type": MEDIA BUY CAMPAIGN,
"order_contact_id": "CN22030000171797",
"billing_contact_id": "CN19120000045227",
"campaign_order_type": "Billboard Custom",
"account_id": "AC19070000001449",
"master_account_id": AC19060000131922,
}
}

Event Campaign Item Payload example

{
"specversion": "1.0",
"id": "e689c2da-f5e2-5837-9de4-1f4136dea7a6",
"source": "urn:sproutloud:broadcasts",
"type": "sproutloud.campaigns.campaign.item.coordination_started.v1",
"datacontenttype": "application/json",
"time": "2022-11-30T04:47:11Z",
"data": {
"reference_id": "CA22110000558195",
"campaign_item_id": "CI22110000558196",
"campaign_item_name": "11x6 GM MD test profile",
"order_type": Billboard Custom,
"template_id": "TM20090000464942",
"master_account_id": "AC19060000131922",
"vendor_id": "VV10090000002309",
}
}

Event Account Attributes Payload example

{
"specversion": "1.0",
"id": "5accb4c3-a8b5-5db0-aa76-71380dd9c123",
"source": "urn:ansira:broadcasts",
"type": "ansira.accounts.account.attributes.updated.v1",
"datacontenttype": "application/json",
"time": "2024-10-29T23:20:47Z",
"data": {
"attributes": {
"Fist Account Attribute": "Value",
"Another Account Attribute": "Another Value",
}
"previous_attributes": {
"Fist Account Attribute": "Old Value",
"Another Account Attribute": "Another Old Value",
}
"master_account_id": "AC23080000180001",
"tp_account_id": "myTpAccountId"
}
}

Retry Policy

Whenever the Broadcaster component attempts to broadcast an event to the third-party system and receives a non-successful status code or timeout, it will be retried multiple times over the following 3 days. The delay between each retry will exponentially increase until the maximum number of retries is reached. Additionally, if a webhook fails multiple times within two weeks, the webhook will be disabled by the broadcast system. Once the communication issue is resolved, the webhook can be manually re-enabled through the Webhook Management interface. Keep in mind the Target URL must be valid and tested before the webhook can be re-enabled.

 

Webhook Signature

The signature allows your system to ensure the webhook came from Ansira and is unaltered.

The signature is generated by using HMAC_SHA256 as follows:

• Signature = HMAC_SHA256 (message, secret)
  • message = now_datetime JSON payload
  • now_datetime = the current date and time in UTC formatted per ISO 8601
  • JSON payload = the body of the POST call (broadcast event in CloudEvents spec)
  • secret = shared secret for the webhook

Example:

• Webhook is called on 2022-01-01T18:45:00Z and contains a sample payload of {“event”: “order.placed”} with the shared secret of my-secret
  • Note: The actual payload has been simplified for this example and will contain more data points and follow the CloudEvents specification.
• HMAC_SHA256(‘2022-01-01T18:45:00Z{“event”: “order.placed”}’, ‘my-secret’)
• c0c834d8b9a68164a968ca2830e1852d90c5730f662b33dc4b421c4a37695553

This HMAC signature and the calculated now_datetime (ISO 8601) MUST be included as request headers when sending the POST call to the Webhook URL.

Request Header	Value
x-sproutloud-signature	c0c834d8b9a68164a968ca2830e1852d90c5730f662b33dc4b421c4a37695553
x-sproutloud-timestamp	2022-01-01T18:45:00Z

Update Webhook

Edit a webhook subscription attributes. Fields that are not included in the list will be ignored.

1) In the Webhooks main page, identify the Webhook to edit, click on Actions then click on Edit.

2) Make your edits to the webhook and click save.

Pause Webhook

Webhooks can be temporarily paused to prevent broadcasts from being sent. You can reactivate the webhook at a later time. Keep in mind however, that events are not kept in a queue while the webhook is paused. This means that any events that were produced while the webhook was paused will not be broadcasted when the webhook is resumed.

1) On the Webhooks main page, identify the Webhook to pause, then click on Actions and click on Pause.

2) A confirmation message will be displayed warning you that by pausing the Webhook, the Ansira system will stop broadcasting this event

3) After clicking Yes, Pause Webhook, you will be returned to the main view, where you will see the Webhook status changed to Paused.

Delete Webhook

1) In the Webhooks main page, identify the Webhook to be deleted, then click on Actions and click on Delete.

2) A confirmation message will be displayed warning you that by deleting the Webhook, it will stop receiving events. Note: events that are already in transit will still be delivered. This process is irreversible, it is recommended to be careful when deleting Webhooks.

3) After the Webhook is deleted, you will be returned to the main view where all the client's Webhooks are listed

List Broadcast Logs

Broadcast logs show you what happened behind the scenes with your webhooks and when it happened, so that if something goes wrong with your events, you have a detailed record of every action before the anomaly.

The logs are also useful, even when everything is working properly. By reviewing the logs you can get insights into how your webhook setup performs, and perhaps improve it.

List broadcast logs using sort, and filter criteria

1) On the Webhooks main page, on the right side of Add a Webhook, you will find the Broadcast Logs button, click on it.

2) When you enter the Broadcast Logs main view, you can see a list with all the call logs of each of the Webhooks.

When you expand a log, you can see the request headers and on the right side, you can also see the body of the request (reference_id, type, account_id, timestamp).

In the Response panel, the headers are shown while on the right side, you will see the body of the response.

The Logs view has filters for Date, Status, TP Webhook ID, Event ID, Event Type, and Target URL

Logs are kept for one year and cannot be recovered once deleted. Logs allow you to test the communication between Ansira and your system and troubleshoot issues in case of failure

Resolution of common problems.

Listed below are some of the most common problems that can be encountered with Webhooks:

• The Webhook doesn’t send events: The Webhook could be paused. To activate it and continue receiving notifications, follow the steps shown in the Pause Webhook section.
• The Signature Secret is invalid: You can review how the signature is generated from the Webhook Signatire section or update secret from the Update Webhook section.
• My system is missing events: You can find the list of all the events the Ansira application generated, includind the response from your system. More information available in the List Broadcast Logs section.