Webhooks
Everything else on this page is the assistant asking a question. Webhooks are the other direction — a system telling the assistant that something happened.
Everything else on this page is the assistant asking a question. Webhooks are the other direction — a system telling the assistant that something happened.
What a webhook carries, and why that matters here
A webhook is a notification sent by a system when an event occurs: an order shipped, a case closed, a payment received, a status changed. Rather than the assistant polling to ask, the system tells it.
For an assistant this enables a category of behaviour that lookups cannot: proactive contact. Telling a customer their order shipped is more useful than being able to answer if they ask, and it removes the contact rather than handling it.
- Event notifications — what happened, and to which record.
- Payloads — the detail accompanying the event.
- Delivery — confirmation the notification arrived.
- Verification — establishing the notification genuinely came from the system.
- Retry — what happens when delivery fails.
What webhooks let Elbi tell people first
Your order has shipped
Proactive notification rather than waiting to be asked.
Your case has been updated
Status change communicated at the moment it occurs.
Payment received
Confirmation, which removes the largest category of payment contact.
Your application progressed
Movement in a process the applicant is waiting on.
Something needs your attention
Prompts for action, where you configure them.
An issue has been resolved
Closing the loop on a reported problem.
How Elbi receives and acts on a webhook
- Your system posts an eventWhen something happens, such as an order shipping or a case changing state, the source system sends an HTTPS POST to an endpoint set up for your deployment. The body names the event type, the record it concerns and when it happened.
- The signature is checked firstEach delivery carries a signature, typically an HMAC computed over the raw body with a secret your team generates, and often a timestamp so an old message cannot be replayed. A delivery that fails the check is rejected and never reaches a customer.
- Acknowledge quickly, act afterwardsValid events are acknowledged promptly and handled after the response is sent. Senders treat a slow or failed response as a reason to retry, so a quick acknowledgement avoids a stack of duplicate deliveries.
- Duplicates and disorder are expectedRetries mean the same event can arrive twice, and events do not always arrive in the order they happened. Each event ID is recorded so a repeat is ignored, and timestamps are compared so a late "shipped" never follows a "delivered" message to the customer.
- Thin events, current detailsWhere the source allows it, the event carries only its type and a reference, and Elbi reads the current details through a scoped lookup before saying anything. The message then reflects the record as it stands, and less personal data travels inside the webhook.
- Only agreed, consented messages go outAn event becomes a message only if its type is on the agreed list and the customer has consented to that kind of contact, in their registered language. Events that need judgement, such as a failed payment, can go to a person instead.
Webhook security, delivery and what stays yours
| Direction of access | Inbound only: your system decides which events it sends. Event types that are not on the agreed list are ignored, and any lookup made in response uses a separate, read-scoped credential. |
|---|---|
| Who can see what | Each event is tied to one record and one customer. A notification goes only to the person the record belongs to, through the channel they agreed to, and never to anyone the payload merely mentions. |
| Credentials | The signing secret is generated on your side and can be rotated or revoked whenever you choose. Disabling the webhook in your own system stops the flow at its source, without involving us. |
| Where data goes | Payloads are used to decide whether to send a message and how to word it, not kept as a copy of your records. Message content is destroyed within 24 hours, and no external AI service sees it. |
| Audit | Each delivery is logged with its event ID and type, whether the signature passed, and which message, if any, was sent as a result. That answers "why did this customer get this message" after the fact. |
| If it is unavailable | If the endpoint is briefly unreachable, your system's retries cover the gap. An event that cannot be processed is logged as failed rather than dropped quietly, and nothing unverified is ever sent. |
What this replaces
Proactive notification changes the economics of contact more than any lookup does. A customer told their order shipped does not ask where it is. An applicant told their case moved does not chase it. The contact is removed rather than absorbed.
The discipline required is restraint. Notification is easy to over-use, and an assistant that messages people frequently becomes something they mute — after which it cannot reach them when it matters. Fewer, higher-value notifications outperform comprehensive ones consistently.
Consent is the other requirement. Proactive contact is a different permission from answering a question, and it needs to be captured explicitly rather than assumed from a service relationship.
Where webhook-driven notifications earn their place
E-commerce
Shipping and delivery notifications that remove chase contact.
Government services
Application progress at each stage.
Banking
Payment and transaction confirmation.
Service desks
Ticket updates without the requester asking.
Getting value from webhooks
Pick the events people currently chase. The best first webhook answers a question customers already ask repeatedly: shipped, payment received, application moved to the next stage. If nobody asks about an event today, a notification about it is unlikely to be welcome.
Start with one event type from one system and measure the chasers it was meant to remove, then add the next. It is tempting to subscribe to every event a platform offers; most describe internal steps customers neither understand nor care about.
Pair each notification with an answer. When someone replies to "your case has been updated", Elbi should be able to look the case up and explain the update, which is why webhooks work best alongside a read connection to the same system.
What connecting a webhook involves
- Choose the events and the wordingList the event types that will produce a message, who receives each one, and the Arabic and English wording. Events meant for staff rather than customers are listed separately.
- Register the endpoint and create the secretYour team registers the endpoint in the source system's webhook settings, over HTTPS, and generates the signing secret there. Where the source supports it, an IP allowlist or mutual TLS can be added on top.
- Agree the payloadDecide whether each event carries full details or only a reference to look up, and which fields identify the customer and the record. Smaller payloads are easier to defend.
- Map consent and languageEach notification type is matched to the consent it depends on and to the customer's registered language, so nothing reaches someone who has not agreed to it.
- Test retries, duplicates and bad signaturesReplay the same event, send events out of order, send one with a wrong signature, and take the endpoint offline to watch the source retry. Each case should behave predictably before a real customer is involved.
- Go live with one event, then addRun a single event type for a month, check the chasers it removed and the opt-outs it caused, then widen.
Personal data inside webhook payloads
A webhook payload is personal data in transit: an order event can carry a name, a phone number and an address, and a payment event more than that. Under the Saudi Personal Data Protection Law, sending it to Elbi is a disclosure your records should cover, and the simplest way to keep it defensible is to send less: an event type and a reference, with details read only when a message needs them.
Proactive contact also needs its own consent, separate from the consent to answer a question, and an easy way to stop it. Once a message has gone, the conversation content that follows is destroyed within 24 hours.
What organisations typically see
Alternatives to webhooks, and when each fits
Webhooks are the right way in when the source system can send them and the event is something a person is waiting for. Most modern SaaS platforms offer them, and many payment and delivery services use them as their main way of reporting what has happened.
Where a system cannot send webhooks, polling is the fallback: checking at intervals for records that have changed. It is simpler to set up but slower to notice and heavier on the source, so it suits low-volume events. In larger organisations, events often already flow through a message broker or an event-streaming platform, and subscribing there can be cleaner than adding webhooks to each system. And some notifications are better left to the source system itself, by SMS or email, where it already sends them reliably.
Whichever mechanism you use, the common failure is volume. An assistant that messages people too often becomes something they mute, and after that it cannot reach them when it matters.
Common questions
Only where you configure it and they have consented. Proactive contact is a separate permission from answering questions.
Signature verification establishes that it genuinely came from your system rather than from someone imitating it.
Retry behaviour is configured. A missed notification should not become a silent failure.
No. A webhook sends only what your system chooses to send, to an endpoint you register. Nothing can reach back through it; any lookup Elbi makes uses a separate credential that you issue and can revoke.
That is normal. Every platform names its events and shapes its payloads differently, and the mapping from your event types and fields to messages is done during deployment.
Not by default. A webhook is a one-way notification. Where a follow-up action makes sense, it goes through a separate connection that you enable deliberately and can keep behind a person's confirmation.
Turn your systems' events into timely messages
Notifications in Arabic and English, sent only for the events you choose and only to people who agreed to them.