The campaign went out. Now comes the question nobody can answer without exporting something: who received it? The status of each send exists, but it lives in the provider’s panel. The return webhook brings that status back into the customer record, where it serves the next decision.
How the webhook works
When a message’s status changes, the provider makes an HTTP call to a URL you gave it. The body of the call carries the event: the message identifier, the new status and other data that varies from provider to provider.
On your side, someone has to receive that call, respond quickly and write the status. Responding quickly matters: if the response takes too long, the provider considers it failed and tries again.
In DeepMiner, receiving only checks the URL and puts the event in a queue, responding right away. Processing happens just after, outside the provider’s call.
Finding the right record
The event says which message changed status. You need to know which customer received that message. There are two common ways to make that link.
The first is to send a record reference along with the message, which the provider returns in the event. The second is to store the identifier the provider returned at send time and look it up when the event arrives.
DeepMiner uses both. It looks first for the record reference and, if there is none, for the message identifier stored at send time. The search is restricted to the partner’s indexes linked to that provider. When nothing matches, the event is logged as unmatched.
What to write on the record
The status alone already helps, but the record becomes more useful with a bit of context. For each channel, DeepMiner writes the status, the date of the last update and the event fields defined for that provider type. The full event goes into the record’s history, which keeps the latest events from all providers.
Because each channel writes its own fields, the same customer can have the SMS status and the RCS status side by side, visible in the index’s record list.
Duplicates and URL security
Repeated events happen, and writing twice messes up the history. DeepMiner identifies the body of each event already applied and marks the repetition as a duplicate. The mark is only written after the update succeeded, so a failure midway lets the event be applied on the next attempt.
The URL is the webhook’s credential. Whoever knows it can send events. That is why, in DeepMiner, each provider has its own URL with a random token, shown only once. Only a signature of the token is stored. If the URL leaks, Regenerate token creates a new one and the previous one stops working. Before applying any event, DeepMiner checks again that the provider is still active and that the token is still the same.
The log of every event
When a status does not show up, the first question is whether the event arrived. The webhook log answers: each event appears as processed, duplicate, unmatched or failed, with the payload for review. The record detail shows the events from that customer’s providers.
What changes afterward
With the result on the record, campaign tracking lives in three places. The run shows the total records, the sent messages and the failures. The index’s record list shows the status of each channel per customer, and the record detail keeps the events. The webhook log shows what arrived from the provider and what found no record.
Want to see a return event reach a record? Book a demo.
Frequently asked questions
What is a return webhook?
It is a URL that the messaging provider calls to report that the status of a send has changed. The receiving system writes that status wherever it is useful.
Why does the same event arrive twice?
Providers usually resend when they do not get a confirmation in time. The receiver needs to recognize the repeated event and not apply the same update again.
How does DeepMiner know which record an event belongs to?
By the record reference sent along with the message, or by the message identifier the provider returned at send time. Only the indexes linked to that provider are considered.