Webhooks
A webhook is an automated message sent between applications when a specific event happens, acting like a "reverse API" that pushes data in real-time instead of the receiving app constantly asking for it. When an action occurs (e.g., a new user signs up, a payment is made), the source system sends an HTTP POST request with event data (a payload in JSON/XML) to a specific URL (the webhook endpoint) provided by the other app, triggering an action there instantly.
Good to know: In Heart.work, an event topic is also named an atomic.
As webhook inform other, external system of changes it can only act on changes in the system. Like write operations, such as POST/PUT/DELETE operations. They are not available for GET operations.
How it works
-
Subscribe to a topic (Register): You provide a unique URL (endpoint) from your application to another service (e.g., Marketo, GitHub). An event triggers: Something happens in the source system (e.g., a new lead, a code commit).
-
Data is sent: The source system automatically sends an HTTP request containing data about that event to your registered URL.
-
Your app responds: Your application receives the data and performs an action, then sends back a simple "Success" message.
Listing Atomics per Workspace
Use the the core-api/webhooks/topics resource endpoint to list the available atomics (event topics) for the current workspace. Note that in Heart.work Core API and Heart.work One, the (listing of) available atomics may be limited per workspace. Contact your account manager can be contacted to have others enabled.
In Heart.work One, registered atomics can be found underneath: Data Studio > Webhooks.
Configuration of Webhooks
Webhook: Delivery Endpoint
The fully qualified domain name (FQDN) and full url for where to deliver the endpoint.
Webhook: SkipSystem
A toggle flag that allows you to overwrite default (Heart.work) system processes. By default is set to skipSystem: false.
Webhook: Headers
Optional list of HTTP headers to be provided for the delivery endpoint. Can be used, for example, for authentication headers.
Webhook: Enabled
A toggle flag indicating the status of the webhook; if it's active (true) or disabled (false).
Remarks & Gotchas
- Webhooks are only available in the Core API.
- You can register multiple webhooks for the same atomic (event topic), optionally providing different delivery endpoints or other characteristics.