Webhooks
Overview
Aprimo Productivity Management webhooks are lightweight, event-driven HTTPS callouts that notify your web service when specific events occur in Aprimo. These events can include actions like record creation or reaching a certain point in a process.
Key Features:
- Event Notification: Webhooks send a JSON message containing contextual information about the triggered event.
- HMAC Validation: Each message includes an HMAC for verification.
- Additional Data: If more details are required, you can use the REST API to retrieve additional information.
Trigger Events
Webhooks can be enabled for:
- Object creation, updates, or deletions on specific objects.
- Specific points in a workflow.
Behavior:
- Webhooks are triggered for every relevant event.
- The receiving service determines if the message requires action. For example, a webhook for activity creation will trigger for all created activities, regardless of type.
Handling Unsuccessful Callouts
- Retries: If a response isn’t received within 30 seconds, the webhook will retry up to 4 times over 24 hours.
- Failure: After 5 consecutive failures, the subscription is invalidated, and system administrators are notified via in-app messaging.
- Manual Retries: Webhooks can be retried manually in the Integration Log.
Webhook Payload
Webhook callouts are sent as HTTP POST requests to a specified URL. Below is an example payload:
{
"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",
"ParentEventId": "7f81c80f-200e-4d45-96d1-f041bbc350ff"
}
"Body": null: Thenullvalue is not applicable for task status action callout location 100."ParentEventId": This is populated when retrying a webhook, referencing theEventIdof the previous attempt.
Webhook Fields
The fields in the webhook payload are defined as follows:
- CalloutLocation: Indicates the type of webhook (integer). See the table below for a list of all
CalloutLocations. - DatasourceId: An internal value used by Aprimo for diagnostics. Can be ignored.
- CalloutType: The Aprimo Object ID for creates, updates, or deletes, or a webhook ID if triggered by a task status action.
- ObjectTypeId: The Aprimo Object ID for creates, updates, or deletes, or
9963for task status actions. - ObjectId: The ID of the record that triggered the webhook.
- CreatingUserId: The Aprimo User ID of the user who triggered the event. This could be a system user for automated processes.
- RetryCount: The number of times the webhook has been retried.
- Body Id: Used by Aprimo for diagnostics. Can be ignored.
- EventTime: The UTC time when the event occurred.
- EventId: A unique identifier for the event, consistent across retries.
Callout Locations
| 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 |
| Project Role Changed | 107 |
| Commitment Approval Approved | 120 |
| Commitment Approval Rejected | 121 |
| Commitment Cancelled | 122 |
| Forecast Changed on Activity | 123 (Rel. 109) |
| Segmentation Started | 140 |
| Segmentation Completed | 141 |
| Segmentation Failed | 142 |
| Segment Completed | 143 |
| Program Proposal Submitted | 160 |
| Activities Added or Removed in a Program | 161 |
| Activity Linked or Unlinked in Content Plan | 162 |
| SSO User Created | 500 |
| SSO User Updated | 501 |
Task Status Action Additional Fields
Task status action webhooks include extra fields within the Body:
- Project_Id: The project ID associated with the task that triggered the action.
- Step_type: The workflow step type for the task. Different step types may require specific REST API calls for additional data (e.g., review tasks may contain more data than basic tasks).
- Test_mode: Indicates if the webhook was triggered during workflow testing. Used by receiving services to determine whether to take action.
Example Payload for Task Status Action
{
"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"
}
Body must be a string.
Integration Log
The integration log and the WebHook publisher service may display the JSON payload fields in a different order. While the structure may vary, the content remains the same. All entries are linked by the Event ID GUID attributes.
Retries
-
Handling Unsuccessful Callouts: If a response isn’t received within 30 seconds, the webhook will retry up to 4 times over a couple of minutes/hours depending on the retry schedule.
-
Retry Conditions: The retry mechanism uses exponential backoff with jitter, retrying webhook requests up to four times. Each retry interval increases exponentially and randomly based on the attempt count. The initial request is sent within one minute by default.
-
Retry Schedule:
Retry Attempt Delay (Minutes) 0 (Initial) 1 1 2 2 5 3 7 4 15 -
Best Practice: Return a response as quickly as possible and perform additional processing asynchronously to avoid unnecessary timeouts and retries.
Logging
- To view triggered webhooks, navigate to the Integration Log under Aprimo’s System Tools section.
- If this section is unavailable, contact support to enable the
integration-logfeature flag for your tenant.
HMAC Validation
When receiving a webhook, validate its authenticity using the HMAC provided in the HTTP header X-SH1.
Steps to Validate:
- Use the secret key you provided as the HMAC key.
- Generate a Base64-encoded HMAC of the HTTP body content using the
HMACSHA256algorithm. - Compare the generated value to the
X-SH1header value. If they match, the message is valid.
Additional Resources:
Example: C# Code to Calculate 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," "Object Updated," and "Object Deleted"
Webhooks triggered by "Object Created," "Object Updated," or "Object Deleted" are only supported for the following objects:
| Object Name | Webhook Sub Type ID |
|---|---|
| Activity | 1 |
| Activity Cells | 10100 |
| Activity Forecasts | 6113 |
| Activity Offers | 9714 |
| Activity Proposals | 3 |
| Attachments | 6214 |
| Brands | 10065 |
| Calendar Events | 6069 |
| Clients | 10056 |
| Commitments | 6135 |
| Content Plan | 5000 |
| Currency Exchange Rates | 10270 |
| Digital Assets (from 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 |
Managing Webhooks
Creating, Updating, and Deleting Webhooks
Webhooks can be managed within the application UI under: System Tools > Integration > Webhook Subscriptions.
Designing for Webhooks
Key Considerations:
- Message Order: Webhooks are not guaranteed to be delivered in chronological order. For example, an "Object Created" webhook might fail and retry later than an "Object Updated" webhook.
- Best Practice: Use the REST API to retrieve real-time data when processing webhook messages.
- Response Time: If the webhook publisher does not receive a
200 OKresponse within 30 seconds, it will assume failure and enqueue a retry.- Recommendation: Respond immediately to webhook callouts and perform additional processing asynchronously.
- Irrelevant Responses: Avoid returning status responses from unrelated REST API calls, as they are not relevant to webhook operation.
Integration Callouts in Workflows
Integration Callouts are a type of webhook that fires when a task reaches a specific status within a workflow (e.g., "In Progress"). These are also known as Task Status Action Webhooks (CalloutLocation: 100).
Setup Steps:
- Navigate to System Administration > Integration > Webhook Subscriptions.
- Select Task Status Action for the "WebHook Source Location."
- Assign a Title, which will appear under the workflow's Integration Callout section as a selectable option.
- Attach the webhook to specific workflow events.
- Note: It may take up to 15 minutes for the webhook subscription to become fully active.
mTLS Security in Webhooks
Aprimo Productivity Management supports optional mTLS authentication for webhooks.
Key Features:
- A global certificate is used to sign requests to verify they originate from Aprimo.
- You can validate the certificate using Aprimo’s public key certificate.
Steps to Enable mTLS:
- Obtain Aprimo’s public key certificate by contacting your Aprimo representative.
- Enable the Send mTLS Certificate With WebHooks system parameter:
- Go to Administration > Configuration > System Parameters > System > Security.
- Note: Changes may take up to 15 minutes to take effect.