This article explains how to configure, receive, and process real-time event notifications (webhooks) from external systems.
Your external system will include a list of scopes that are possible. Generally, there will be one for each combination of mapping collection type and scope action (e.g., one for product created, one for product updated, one for product deleted, etc.). If your system has multiple hooks for a single action/mapping collection type, you can add all of them. For example, you may have order/updated and order/messageAdded, both of which would be update hooks for a transaction. Note that the actual scope name used by a given hook will never be passed to your integration. In the example above, you would only know that one of your transaction update hooks came in; you would not know which one.
When defining your scope, the description should include the name of the data type in the external system and in iPaaS.com (if they are different). For instance, if an iPaaS.com Transaction maps to an Order object in the external system, it can facilitate data integration. If a platform has its own webhooks, we always create the iPaaS.com scope with the same name for simplicity.
Occasionally, you may encounter a system that does not give you a way to properly determine the scope without some system-specific values. For example, the external system may allow users to rename “product” to “item”. In this case, you would not have a consistent scope coming in, and you would need to access a system-specific setting to determine what the type applies to. The only way to do this is in your integration, after the scope has been resolved. In this case, you could resolve all incoming hooks to a single scope value (such as message/created), extract any necessary identifiers as the external id, then use the HandlePrerequisite function to determine the real scope value and create a corresponding TransferRequest.
Example: We integrate with a system that sends hooks with a data type prefix and an id, e.g., Car:1234. The prefix indicates the data type, but the values will vary between implementations. So we provide Presets to specify the datatypes for Products, Categories, etc. Every hook is initially sent as message/created for the scope, but the following code in the HandlePreRequisites method converts the call to the appropriate type:
//Determine the prefix of external idvar prefix = transferRequest.ExternalId.Substring(0, transferRequest.ExternalId.IndexOf(':'));//Convert that prefix into a mapping collection typevar matchingType = StandardUtilities.FindMatchingClassType(prefix, conn);//Convert the mapping collection type into a valid scopevar scope = StandardUtilities.ConvertMappingCollectionTypeToScope(matchingType, (int)ScopeAction.UPDATED);//Now we have everything to initiate the real transfer. Build a transfer requestvar childRequest = new TransferRequest(connection: conn, externalId: transferRequest.ExternalId, mappingCollectionType: matchingType, mappingDirection: transferRequest.MappingDirection, scope: scope, childRequest: true);//Execute the transferawait conn.DataHandlerFunctionAsync(childRequest);Note that for this to work, you must have a valid mapping collection defined for your control type. In the example above, we must define a valid message mapping collection.
Some systems may include hooks with a payload that involves multiple transfer requests. This is generally supported using standard dynamic webhook processing. See the Dynamic Webhook Processing Expression Variables for more information on multi-hook support. Each transfer request will be processed independently, so there is no need for additional handling beyond your dynamic webhook configuration.
You will likely need to add scopes beyond what is defined by your external system. For example, if you support polling, but there is no polling hook, you will need to create one. Conversely, if your external system defines a polling hook, but not standard create or update hooks, you will need to define those so that the hooks spawned in a polling transfer can use them.
Be cautious with enabling delete hooks. In many cases, deleting a record in one system should not delete the record in other systems. For example, if you delete a product from your website, you do not necessarily want to delete it from your Point of Sale system. This is especially true during initial implementation, when entries may be deleted and resynced several times. Delete triggered updates are safer and more flexible.
Another issue with delete hooks is handling a transfer when the source data no longer exists. If you delete a record in your external system, it may fire a hook to iPaaS.com, but iPaaS.com will generally not be able to access the details of the deleted data beyond the id that arrived with the hook. Ensure that any delete triggered update mappings will work with this limited data.
If you receive a hook for child data that cannot be transferred independently, by convention, this should be converted into a parent hook. For example, if a customer address hook arrives, but updating customer addresses independently of the customer is not supported, create a transfer request for the parent.
Weigh the benefits of this policy against any possible performance considerations. For example, if a customer address is updated every time it is used in a mailing or batch export, it might be better to ignore those hooks, rather than initiating an entire customer transfer.