Tamr’s event-driven notification system enables you to keep all of your systems up to date with the golden records in the Tamr System of Record (SOR).
Tamr can publish Realtime notifications for these logical actions to a user-specified endpoint (a webhook):
- Create golden record
- Update golden record
- Delete golden record
- Merge golden record
- Unmerge golden record
- Enrich golden record
The notifications are published as HTTPS POST requests. The webhook receives these requests and sends messages with the event data to a subscribing application or portal. For example, when a new record is created in the SOR, Tamr publishes a notification to the specified webhook, which then sends the CREATE event to a consumer application such as a CRM.
Merge and Unmerge Logical Actions
For golden record merge actions, an UPDATE event is published to update the data in the surviving golden record. A DELETE event is sent for the retired golden record. These two physical events are grouped together as one logical event by the same versionId value. They are ordered by two different values for recordNumber.
For golden record unmerge actions, an UPDATE event is published to update the data in the surviving golden record. A CREATE event is sent for the previously retired (resurrected) record golden record. These two physical events are grouped together as one logical event by the same versionId value. They are ordered by two different values for recordNumber.
Example Webhook Events
| Logical Action | Webhook Record Event | |||
|---|---|---|---|---|
| versionId | changeType | recordNumber | newData | |
| Create Record | 12355 | CREATE | 0 | The record data of the created record. |
| Update Record | 23435 | UPDATE | 0 | The new record data resulting from the update record action. |
| Delete Record | 33256 | DELETE | 0 | Empty object. |
| Merge Record | 44566 | UPDATE | 0 | The new record data of the surviving record. |
| DELETE | 1 | Empty object. The retiring record has been deleted. | ||
| Unmerge Record | 54536 | UPDATE | 0 | The new record data of the retained record. |
| CREATE | 1 | The new record data of the resurrected record. | ||
| Enrich Record | 64729 | UPDATE | 0 | The new record data resulting from Tamr enrichment of the record. |
Webhook Requirements
Client Webhook Requirements
Your organization must have an HTTPS endpoint that can capture the change data sent from Tamr Cloud via HTTPS POST.
The endpoint service must:
- Support throughput commensurate with the user’s Tamr RealTime authoring throughput. Tamr publishes notifications in near real-time as authoring events occur in the SOR.
- Be capable of processing requests idempotently, which allows Tamr to safely replay the messages from a given time range as needed.
Webhook Integration Requirements
When configuring a webhook integration, you must provide an authorization header value for Tamr to use to access your webhook endpoint. For example:
- A basic auth header (
BasicCreds) - An API key header (
X-API-KEY)
Configuring a Webhook Integration
To add a connection to your webhook endpoint:
- Navigate to Admin Center > Connections.
- Select New Connection.
- Choose the Webhook connection type.
- Provide the webhook URL and enter each header value as a key/value pair. Choose the Sensitive option to hide the value in the Tamr Cloud UI.
- Select Add to save the webhook.
Key/value examples:
| Key | Value |
|---|---|
| Authorization | Basic |
| Content-Type | application/json |
Webhook Payload Format
Webhook payloads follow the CloudEvents standard. CloudEvents is a specification for describing event data in a common format to provide interoperability across services, platforms and systems. The CloudEvents specification defines a standard envelope for event data. For ease of adoption, CloudEvents SDKs are available in a variety of languages.