Receive events with webhooks

A webhook sends an event from Aihio to your HTTPS endpoint. Use it to pass captured contact details to your own system or start handling a question the agent could not answer.

A webhook reports an event. If the agent needs to fetch information or perform an action during a conversation, use an HTTP action instead.

You need a subscription that supports webhooks, permission to manage the integration and an HTTPS receiver reachable from the public internet. The receiver must verify signatures, handle duplicates and accept events promptly. Requests cannot be sent to private network addresses.

1. Prepare an HTTPS endpoint

   Create a server endpoint that receives POST requests. Retain the original request body for signature verification before parsing JSON.

2. Add the webhook in Aihio

   Open the integration settings in Oma Aihio. Add a webhook for the agent, enter the receiver’s HTTPS URL and select the events you need. Store the provided signing secret in the receiver’s protected configuration.

3. Check one event end to end

   Trigger the selected event using test data. Verify the event type, accepted signature and successful processing at the receiver. Also check the delivery status in Aihio.

The shared JSON envelope fields are event, created_at and data. data contains event-specific content. Select handling by event; do not assume that every event contains the same fields.

Requests include these headers:

The signature is an HMAC-SHA256 digest of timestamp.rawBody. The timestamp is Unix time in seconds and the digest is lowercase hexadecimal.

1. Read t and v1 from the signature header. Reject missing or malformed values.
2. Check that the timestamp falls within a short acceptance window chosen for your receiver. Keep the server clock synchronized.
3. Calculate the expected digest using your stored secret and the exact incoming body. Reformatting JSON changes the signed content.
4. Compare digests using a constant-time comparison before using the event.
5. Process the same X-Aihio-Delivery only once, even if the request arrives again.

The presence of the header alone does not prove authenticity. Also test an invalid signature: the receiver must reject it without side effects.

Return a successful HTTP status only after safely accepting the event. Move lengthy processing to your own reliable queue; the sender’s timeout is 10 seconds. Do not acknowledge successful receipt when acceptance failed.

Aihio retries failed deliveries a limited number of times. The current maximum is three attempts. Delivery is not exactly-once processing and retry timing is not guaranteed. Ensure that repeated requests cannot create the same contact twice, for example.

• Check that the webhook is enabled and subscribed to that event.
• Check endpoint reachability, the TLS certificate and receiver status codes without logging personal data.
• If the signature does not match, check the secret, original request body and server clock.
• If processing takes too long, move work to a queue and promptly acknowledge safe acceptance.

Disable the webhook before deleting its receiver or closing the endpoint. Retain the delivery ID and error time for support; never include the secret in a support request.