P4 Software / activoHQ English

Webhooks

Webhooks

Overview

A webhook notifies another system when an asset life-cycle event happens. ActivoHQ sends an HTTP POST to the address you give, carrying the same payload the automation rules use: asset disposed, revalued, checked out, checked in, checkout overdue and RFID variance detected.

It is the way to integrate ActivoHQ with your ERP, your help desk, a messaging channel or any service of your own, without that system having to poll the API.

Deliveries are retried automatically and their result is visible on the same screen.

How to get there

Settings > Webhooks

Direct URL: /Settings/webhooks

The screen describes itself as: POST the same lifecycle-event payload Automation rules use to your own URL - asset disposed, checked out/in, RFID variance, and more. Deliveries are retried automatically and shown below.

Key concepts

Term Definition
Subscription A URL plus the list of events you care about.
Delivery Each attempt to send an event's payload to the subscribed URL.
Secret An optional key ActivoHQ signs the payload with, so your system can verify the message really came from ActivoHQ.
Signature The HMAC-SHA256 of the message body, sent in the X-ActivoHQ-Signature header as lowercase hexadecimal.

Available events

AssetDisposed, AssetRevalued, AssetCheckedOut, AssetCheckedIn, AssetCheckoutOverdue, RfidVarianceDetected

They are the same events the Automation rules use; the screen lists them as valid values beside the Events field.

How to use it

Create a webhook

  1. Click New.
  2. In the New Webhook dialog, fill in:
    • URL (required): the address that will receive the POST, for example https://example.com/webhooks/activohq.
    • Events (required): a comma-separated list of one or more of the valid events - the field's hint reads Comma-separated. Valid values: followed by the list.
    • Secret (optional): the key to sign the payload with - Used to HMAC-SHA256 sign the payload.
    • Active: ticked by default.
  3. Click Save.

If the URL is empty or none of the events given is valid, the system warns: Enter a URL and at least one valid event type.

Review the deliveries

The Recent deliveries section shows, for each attempt:

Column Description
Created The date and time the delivery was generated.
Event The event that produced it.
Status Sent, Failed or Pending.
Attempts How many attempts have been made.
Last error The reason for the last failure, where there was one.

Retries

ActivoHQ processes the delivery queue every minute and retries the ones that were not accepted, up to a maximum of 5 attempts. While attempts remain, the delivery stays Pending; once they are exhausted, it becomes Failed.

Verify the signature in your system

When the subscription has a Secret, each POST carries the X-ActivoHQ-Signature header with the HMAC-SHA256 of the body exactly as received, in lowercase hexadecimal with no prefix. Your system must recompute that HMAC with the same secret over the original body and compare before processing the message.

Edit or delete webhooks

  • To edit, click the URL in the table.
  • To delete one, use Delete in the context menu; for several, tick the checkboxes and use Delete (N).
  • To suspend the sending without deleting the subscription, untick Active.

Fields

Field Type Required Description Validation
URL Text Yes The address that receives the POST. A URL must be given. Only public internet destinations are allowed: internal network, local and cloud internal-service addresses are refused.
Events Text Yes A comma-separated event list. At least one must be valid.
Secret (optional) Text No The key to sign the payload with using HMAC-SHA256. None.
Active Checkbox No Inactive subscriptions receive no deliveries. None.

When there are none, the table shows No webhooks found - Add a webhook to notify an external system automatically when a lifecycle event happens.

Notes

  • Subscriptions are per company.
  • Your service has to answer with an HTTP success code; any other response counts as a failed attempt and is retried.
  • Design your receiver to tolerate repeat deliveries of the same event: a retry can arrive after your system has already processed the message.
  • To notify people rather than a system, use an automation rule on the same event.

Troubleshooting

Symptom Likely cause Resolution
Every delivery shows Failed. The URL does not respond, responds with an error, or requires extra authentication. Check Last error, validate the URL from outside your network and adjust your receiver.
The webhook will not save. The URL is empty, or the events typed are not valid. Copy the event names exactly as the screen shows them.
The company's internal URL is refused. Only public destinations are accepted, for security. Expose a public endpoint (a gateway, for example) that forwards into your internal network.
My system receives the event twice. A retry crossed with a delivery that did arrive. Make the processing in your receiver idempotent.
The signature does not match. The HMAC was recomputed over an already transformed body. Always sign and verify over the original body received.

Related

Was this page helpful?

Previous Automation rules Next Report designer