# Receive events with webhooks

URL: https://aihio.ai/en/help/ai-agent/webhooks\
Description: Send agent events to your system and verify incoming webhook requests.

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](/en/help/ai-agent/actions) instead.

## Before you start

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.

> **Warning — The receiver may receive personal data:**
>
> Select only the events you need and restrict their processing in your system.
> Keep the signing secret on the server. Do not write complete message or
> contact payloads into ordinary application logs.

## Connect your receiver

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.

## Select events

| Event                     | Purpose                                        |
| ------------------------- | ---------------------------------------------- |
| `conversation.unanswered` | Handle a question left unanswered.             |
| `conversation.message`    | Process a conversation message in your system. |
| `lead.captured`           | Process captured contact details.              |

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.

## Verify the signature

Requests include these headers:

| Header              | Content                                        |
| ------------------- | ---------------------------------------------- |
| `X-Aihio-Event`     | Event type.                                    |
| `X-Aihio-Delivery`  | Delivery ID for duplicate handling.            |
| `X-Aihio-Signature` | Timestamp and signature as `t=TIME,v1=DIGEST`. |

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.

## Acknowledgement and retries

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.

## If an event does not arrive

- 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.
## Next steps

- [Custom HTTP Actions](/en/help/ai-agent/actions) — Define an HTTPS API call that the agent fills in and the server runs during a conversation. Credentials are stored encrypted and calls are protected.