Receiving live events with webhooks

Up to now, in API integrations, your system was the one talking to arrobaMail: you requested the token, added a contact, sent. Event webhooks flip that direction: now arrobaMail talks to your system. Every time something happens — a campaign finished sending, someone opened it, an email bounced, someone unsubscribed — arrobaMail sends a notification to a server of yours, the moment it happens.

It's the piece that lets you keep your own data always fresh: audit, sync your database, or trigger your business logic in response to what your audience does. Here's the shape of the flow:

1. What event webhooks are

A webhook is, put simply, a call one system makes to another when something happens. Here, you configure a URL on your server in arrobaMail, and from then on, arrobaMail makes an HTTP POST to that URL every time an event occurs, with the data about what happened. No need to keep asking "did they open it? did they open it?" — arrobaMail tells you on its own.

Careful — don't confuse this with an automation's Webhook node. That one (covered in transactional emails) fires a POST when a contact passes through a point in a flow. The event webhooks in this guide are different: they notify you of email events (opens, bounces…) as they happen.

2. What they're good for

Receiving events live lets you:

• Audit and report with your own dashboards, without ever logging into the platform.
• Sync your database: mark in your CRM who opened, who bounced, who unsubscribed — and keep your records current.
• Take action: trigger business logic when something happens (for example, if an important customer clicks your offer, alert the sales team).

3. Configure your URL

From your account's settings, paste in the public URL of your server that will receive the notifications. It must be HTTPS (unencrypted URLs aren't accepted). Something like:

https://your-server.com/webhooks/arrobamail

That URL is the "mailbox" where arrobaMail is going to drop off every event.

4. The events you'll receive

arrobaMail notifies you of events across your sends' lifecycle. The main ones:

• campaign.sent — a campaign finished sending.
• contact.open — a contact opened an email.
• contact.click — a contact clicked a link.
• contact.bounce — an email bounced (with its type: temporary or permanent).
• contact.complaint — someone marked your email as spam.
• contact.unsubscribe — someone unsubscribed.
• automation.triggered — a contact entered an automation flow.

Each POST carries the event's data (the contact, the campaign, the timestamp). It's worth confirming the exact payload structure in your early tests (covered in step 6).

5. Program the receiver

Your server needs to listen for that POST, read the JSON, run your logic, and respond with HTTP 200 so arrobaMail knows you received it. A minimal PHP receiver:

<?php // webhooks/arrobamail
$payload = json_decode(file_get_contents("php://input"), true);

$event = $payload["event"]   ?? null;   // e.g.: contact.bounce
$email = $payload["email"]   ?? null;

switch ($event) {
    case "contact.bounce":
        // mark the email as bounced in your database
        break;
    case "contact.unsubscribe":
        // unsubscribe it in your CRM too
        break;
    // ...any other events you care about
}

http_response_code(200);
echo json_encode(["status" => "ok"]);

The idea is the same regardless of language: read the body, check the event type, do your thing, respond 200.

6. Test and debug

Before trusting your logic, see what's actually coming through:

• Log the entire payload during your first tests. That way you see exactly which fields arrobaMail sends for each event, instead of guessing.
• Use your account's event history (under Tools) to see the record of what was sent and cross-check it against what your server received. It's the main tool for debugging the integration.

7. Best practices

• Respond fast. Your receiver should return 200 right away. If you have heavy processing to do, queue it and handle it separately — don't make the webhook wait.
• Make it idempotent. The same event can arrive more than once. Design your logic so receiving "bounced" twice doesn't break anything (for example, dedupe by event ID).
• Verify the source. Only accept traffic to your secret URL (and, for extra security, validate the content before acting on it).
• Don't rely on webhooks alone for critical data. For exact reporting, complement them with API queries — webhooks are for reacting live; the API is your consolidated source of truth.

Common mistakes to avoid

• A URL without HTTPS. Not accepted. Your endpoint has to be encrypted.
• Not responding with 200. If your server doesn't confirm receipt, arrobaMail may treat the delivery as failed.
• Assuming the payload format. Log first, code second. Confirm the fields by looking at what actually arrives.
• Doing heavy processing inside the webhook. Queue the work and respond fast, or you'll run into timeouts.

Next steps

1. Review the full picture of every integration path in connecting arrobaMail to your systems.
2. Combine them with sends from your own system in sending transactional emails.
3. See the complete API in REST API v3 and its reference.