A webhook is the way back of an integration: WiseData Mail telling your system what happened to each email β delivered, bounced, opened, clicked, unsubscribed. With it, Casa Moura CafΓ©s' online store knows that a customer's pedido-confirmado bounced and can ask for another email on their next visit.
Setup is done only in the panel, under Settings βΊ Webhooks, and the history lives under Settings βΊ Webhook events. Both tabs belong to the Owner. If they don't show for you, contact support.
Adding a webhook
Click New webhook and fill in:
- Address β starting with
https://and reachable from the internet, such ashttps://casamoura.com.br/webhooks/mail. An address pointing inside an internal network is refused, and redirects are not followed: your server must answer at the exact address you registered. - Description β which system receives these events.
- Subscribed events β check at least one. Two carry their own warning: Accepted by the provider arrives once per message sent (high volume, only worth it if you measure the funnel), and the domain events (Domain ready to send, Domain did not become ready, Domain is no longer ready) are about the domain, not a message, and arrive without a recipient email β your receiver needs to accept that.
- Receive from β shows when the account has sending spaces. With none checked, the webhook receives the whole account, including spaces created later. With spaces checked, it receives only theirs, without the main account's.
- Receive events β turned off, the webhook is Paused.
A new webhook starts receiving from the moment it is created. Events from before setup are not sent.
The secret is shown once
When you save, the Webhook created window shows the secret. Copy it right away: it won't be shown again. Every batch arrives signed, and your system uses this secret to verify the signature before trusting the content. A batch whose signature doesn't match should be rejected.
How events arrive
- In batches β several events per call, not one at a time. In a large campaign, that saves your server thousands of calls.
- Answer 2xx, and fast. Any other response counts as a failure, and the batch is resent automatically. Store the batch and process it later; don't make WiseData Mail wait for your processing.
- Be ready to receive the same batch twice. A resent batch arrives identical to the original; your receiver should ignore what it already processed.
- It is not real time. There are a few moments between the event and the delivery β don't use the webhook to trigger something a person is waiting for on screen.
Active, paused and disabled after failures
- Active β receiving.
- Paused β you turned off Receive events. Turn it back on from the edit form.
- Disabled after failures β after a run of failed batches, WiseData Mail turns the webhook off on its own and the Owner gets an email. The list shows how many batches failed in a row and the date of the last successful delivery.
Before clicking Re-enable, fix your server β otherwise it fails again. And note that events from the period it was off are not resent: the history shows what was left behind. Saving an edit to the webhook also resets the failure count.
Each webhook's buttons
- Test β hits your address right away and shows what it answered (code and time). The test doesn't go into the history and doesn't count toward automatic disabling.
- History β opens Webhook events already filtered on this webhook.
- Rotate secret β generates a new secret and the current one stops working immediately. There's no window with both valid: between the rotation and installing the new one, your server will reject deliveries. Batches that fail in that window are resent automatically, so install the new secret promptly.
- Edit β address, description, events, spaces and the switch.
- Remove β your system stops receiving immediately, and the delivery history is deleted with it. If you only lost the secret, prefer Rotate secret: the history stays.
The delivery history
Under Webhook events, pick the webhook (if there is more than one) and see each batch: When, Status (Pending, Delivered or Failed), how many Events and how many Attempts.
View opens the batch details:
- Body sent β exactly what was signed. When the signature doesn't match on your side, compare it with what your server received: the difference is usually that the body was read already converted, not as it arrived.
- Attempts β each with the code your server answered, the time and an excerpt of the response. no response means the server didn't answer in time or wasn't reached at all β the problem is before your code.
A batch that wasn't delivered has the Resend button, in the table and in the details. Use it after fixing your server to recover what failed.
For integrators
Each event carries the type, the recipient's email, the message, the campaign (empty for transactional), the space it was sent from and, when the send came through the API, the tags and metadata your system sent. Events simulated in the Test inbox reach the same address, flagged as test β ignore them in your production receiver, or a simulated bounce becomes a real customer's unsubscribe.
Where to go next
- Test inbox β simulate a bounce or a click and watch the webhook arrive.
- API keys β the outbound side of the integration.
- Sending spaces β receive events from some spaces only.
In short: add an https address that answers 2xx fast, check only the events your system uses, keep the secret to verify each batch's signature, handle repeated batches, fix the server before re-enabling a webhook disabled after failures, and use the history to find out what didn't arrive.