Webhooks

Aprimo Cloud webhooks are lightweight, event-driven HTTPS callouts from Aprimo Cloud. When certain events happen in Aprimo, such as the creation of a record or reaching a certain point in a workflow, a webhook can make an HTTPS call to your web service and provide a lightweight message in JSON format. An HMAC will also be provided to validate that the message came from Aprimo Cloud. Webhooks contain only contextual information to understand what event triggered the callout. If this information is not enough for your integration, you can call back into the REST API to gather the additional data needed by your integration.

Webhooks may be enabled for specific objects to be triggered on record creates, updates, and deletes, or may be triggered at specific points in a workflow. Webhooks will call out for every event triggered. It is up to the receiving service to determine whether the message should require action. For example, if a webhook is set up on activity creation, any created activity will fire a webhook regardless of the activity type or any other metadata field.

Webhook Payload

Webhook callouts are HTTP POST requests to a URL that you specify.

The payload of a webhook looks like this *:

{
   "CalloutLocation":2,
   "DatasourceId":6011,
   "CalloutType":9952,
   "Title":"object-update",
   "ObjectTypeId":9952,
   "ObjectResourceName":"projects",
   "ObjectId":87701,
   "CreatingUserId":1,
   "RetryCount":0,
   "Body":null,
   "Id":"9672c836-8b9c-44e6-bfbe-c8d028ba963a",
   "EventTime":"2016-10-12T13:19:07",
   "EventId":"7f81c80f-200e-4d45-96d1-f041bbc350ff"
}

* “Body”: null tag null value is not applicable for task status action callout location 100

The fields sent are defined as followed:

  • CalloutLocation indicates the type of webhook in integer form. Title is the readable name for the CalloutLocation. The following titles and calloutlocations are supported today:
Title CalloutLocation
Object Created 1
Object Updated 2
Object Deleted 3
Task Status Action Fired 100
Project Started 102
Project Paused 103
Project Resumed 104
Project Closed 105
Project Cancelled 106
Commitment Approval Approved 120
Commitment Approval Rejected 121
Commitment Cancelled 122
Segmentation Started 140
Segmentation Completed 141
Segmentation Failed 142
Segment Completed 143
Program Proposal Submitted 160
Activities Added or Removed in a Program 161
SSO User Created 500
SSO User Updated 501
  • DatasourceId – An internal value used by Aprimo for diagnostic purposes. This can be ignored.
  • CalloutType – The Aprimo Object ID for creates, updates, or deletes on an Aprimo object, or an Aprimo webhook ID if triggered from a task status action.
  • ObjectTypeId -The Aprimo Object ID for creates, updates, or deletes on an Aprimo object, or 9963 for task status actions. (See below list for supported objects).
  • ObjectId – The ID of record that triggered the webhook.
  • CreatingUserId: The Aprimo User Id of the user who triggered the event. This may be an actual user of the system or a service user if the event was triggered by an automated process.
  • RetryCount: The retry count of this message.
  • Body Id: An ID used by Aprimo for diagnostic purposes. This can be ignored.
  • EventTime: The time the event originally occurred in UTC.
  • EventId: A unique ID for the event, consistent through any retries.

Additionally, task status actions will include the following extra fields in the body:

  • Project_Id: The project ID associated with the task that triggered the status action.
  • Step_type: The workflow step type associated to the task. Different step types may require different REST API calls to get additional data (for example, a review task may have more information than a basic task).
  •  Test_mode: Test mode may be turned on when configuring a workflow status action in the Aprimo workflow designer. This can be used by the receiving service to decide to take actions if workflows are still being tested.

The payload of a task status action webhook looks like this *:

{
   "CalloutLocation":100,
   "DatasourceId":6011,
   "CalloutType":1,
   "Title":"task-status-action",
   "ObjectTypeId":9963,
   "ObjectResourceName":"tasks",
   "ObjectId":87701,
   "CreatingUserId":1,
   "RetryCount":0,
   "Body":{"project_id":1000, "step_type":9, "status":"Approved", "test_mode":0},
   "Id":"9672c836-8b9c-44e6-bfbe-c8d028ba963a",
   "EventTime":"2016-10-12T13:19:07",
   "EventId":"7f81c80f-200e-4d45-96d1-f041bbc350ff"
}

Retries

If a webhook callout receives any HTTP Status in the HTTP Response other than a response in the ‘success’ range (200 to 299), it will queue up a webhook for a retry. The first retry will happen after 1 minute, followed by 2 minutes, 5 minutes, 7 minutes, 15 minutes, 30 minutes, and 60 minutes, at which point retries will continue every 60 minutes until 24 hours have passed. It is recommended that you return a response from the webhook as soon as possible and do any additional processing asynchronously in order to avoid timeouts and extra retries where they are not necessary.

Logging

In order to see what webhooks have triggered, you may navigate to the integration log under Aprimo’s System Tools section to see generated webhooks.

HMAC

It is advised that when you receive a webhook, you validate it with the HMAC to ensure its authenticity. The HMAC will appear in an HTTP Header called X-SH1. To validate the message, use the secret value you provided as a key to generate the base64 encoded representation of the HMAC of the HTTP body content using the HMACSHA256 algorithm and compare it to the header value. For valid messages, these values should match.  You can find details on the Microsoft implementation of the HMACSHA256 algorithm here https://msdn.microsoft.com/en-us/library/system.security.cryptography.hmacsha256(v=vs.110).aspx

Additionally, the following sample C# code illustrates how to calculate this HMAC

using System.Security.Cryptography;
using System.Text;
static string CalculateAprimoWebhookHMAC(string secret, string httpBodyContent)
{
  var payload = Encoding.UTF8.GetBytes(httpBodyContent);
  var key = Encoding.UTF8.GetBytes(secret);
  using (var hash = new HMACSHA256(key))
  {
    return System.Convert.ToBase64String(hash.ComputeHash(payload));
  }
}

Object Support for Object Created, Updated, and Deleted

Only the following objects are supported for firing webhooks on create, update, or delete:

  • Activities (1)
  • Activity Cells (10100)
  • Activity Forecasts (6113)
  • Activity Offers (9709)
  • Activity Proposals (3)
  • Attachments (6214)
  • Brands (10065)
  • Calendar Events (6069)
  • Clients (10056)
  • Commitments (6135)
  • Currency Exchange Rates (10270)
  • Digital Assets (from Digital Asset Library) (39)
  • Expense Categories (10324)
  • Funding Accounts (10235)
  • Generic Object Alpha (10891)
  • Generic Object Bravo (10892)
  • Generic Object Charlie (10893)
  • Generic Object Delta (10894)
  • Generic Object Echo (10895)
  • Incentives (10121)
  • Invoices (6)
  • Journal Vouchers (10345)
  • Notes (6202)
  • Offers (9709)
  • Products (10129)
  • Programs (2)
  • Projects (9952)
  • Roles (9944)
  • Suppliers (11)
  • Tasks (9963)
  • Treatments (9711)
  • Users (12)

Creating, updating, and deleting webhooks

Today, creating and updating webhooks must be done by Aprimo.

Please visit the customer support site and select Get Support followed by Webhook Request.

Input all fields and our team will create the webhook for you and return the secret needed to calculate the HMAC plus the webhook ID as a guid. Save your Webhook ID in case you need to update it in the future.

The following fields need to be supplied:

  • Callout Location should be the number taken from the callout location above.
  • ObjectID should be the ID of objects supported above. This does not need to be supplied for Task Status Action webhook types.
  • EndpointURL should be the url to your endpoint.
  • Task Status Action Name will be the name of the task status action that appears in the Aprimo Workflow designer. This is only set for Task Status action webhook types.

For example, if you wanted a webhook on activity update, you would supply a Callout Location of 2 (Object Updated), an Object ID of 1 (Activities), and your endpoint URL.