Webhook Overview — Real-Time Email Event Notifications

import Ark from 'ark';

const client = new Ark();

const webhook = await client.webhooks.create({
  name: 'Production Webhook',
  url: 'https://yourapp.com/webhooks/ark',
  events: ['MessageSent', 'MessageBounced', 'MessageDeliveryFailed'],
});

console.log(`Webhook created: ${webhook.data.id}`);

require "ark_email"

client = ArkEmail::Client.new

webhook = client.webhooks.create(
  name: "Production Webhook",
  url: "https://yourapp.com/webhooks/ark",
  events: ["MessageSent", "MessageBounced", "MessageDeliveryFailed"]
)

puts "Webhook created: #{webhook.data.id}"

client := ark.NewClient()

webhook, err := client.Webhooks.Create(ctx, ark.WebhookCreateParams{
    Name:   ark.String("Production Webhook"),
    URL:    ark.String("https://yourapp.com/webhooks/ark"),
    Events: ark.StringSlice([]string{"MessageSent", "MessageBounced", "MessageDeliveryFailed"}),
})

fmt.Printf("Webhook created: %s\n", webhook.Data.ID)

curl -X POST https://api.arkhq.io/v1/webhooks \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Webhook",
    "url": "https://yourapp.com/webhooks/ark",
    "events": ["MessageSent", "MessageBounced", "MessageDeliveryFailed"]
  }'

const webhook = await client.webhooks.create({
  name: 'Tenant A Webhook',
  url: 'https://yourapp.com/webhooks/ark',
  events: ['MessageSent', 'MessageBounced', 'MessageDeliveryFailed'],
  tenantId: 'tenant_abc123',
});

curl -X POST https://api.arkhq.io/v1/webhooks \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Tenant A Webhook",
    "url": "https://yourapp.com/webhooks/ark",
    "events": ["MessageSent", "MessageBounced", "MessageDeliveryFailed"],
    "tenant_id": "tenant_abc123"
  }'

import express from 'express';

const app = express();
app.use(express.json());

// In-memory store (use Redis/DB in production)
const processedEvents = new Set<string>();

app.post('/webhooks/ark', async (req, res) => {
  // 1. Verify signature (see Security page)
  verifySignature(req);

  const payload = req.body;

  // 2. Idempotency: prevent duplicate processing
  const token = payload.message?.token ?? '';
  const status = payload.status ?? '';
  const idempotencyKey = `${token}_${status}`;

  if (processedEvents.has(idempotencyKey)) {
    return res.status(200).send('OK');
  }
  processedEvents.add(idempotencyKey);

  // 3. Process based on status (queue to background job in production)
  switch (payload.status) {
    case 'Sent':
      await handleSent(payload);
      break;
    case 'HardFail':
      await handleHardFail(payload);
      break;
    case 'SoftFail':
      // Ark retries automatically
      break;
    case 'Held':
      await handleHeld(payload);
      break;
  }

  // Handle bounces (different payload structure)
  if (payload.original_message) {
    await handleBounce(payload);
  }

  // Handle engagement events
  if (payload.ip_address) {
    if (payload.url) {
      await handleClick(payload);
    } else {
      await handleOpen(payload);
    }
  }

  // 4. Return 200 quickly
  res.status(200).send('OK');
});

async function handleHardFail(payload: any) {
  const { classification } = payload;
  const recipient = payload.message?.to;

  if (['invalid_recipient', 'inactive_mailbox', 'invalid_domain'].includes(classification)) {
    await updateContactStatus(recipient, 'invalid');
  } else if (['spam_block', 'policy_rejection'].includes(classification)) {
    await alertDeliverabilityTeam(payload);
  }
}

class ArkWebhooksController < ApplicationController
  skip_before_action :verify_authenticity_token

  def create
    # 1. Verify signature (see Security page)
    verify_signature!

    payload = JSON.parse(request.body.read)

    # 2. Idempotency: prevent duplicate processing
    idempotency_key = "#{payload.dig('message', 'token')}_#{payload['status']}"
    return head :ok if already_processed?(idempotency_key)
    mark_as_processed!(idempotency_key)

    # 3. Process based on status (queue to background job in production)
    process_payload(payload)

    # 4. Return 200 quickly
    head :ok
  rescue => e
    head :unauthorized
  end

  private

  def already_processed?(key)
    Rails.cache.exist?("ark_webhook:#{key}")
  end

  def mark_as_processed!(key)
    Rails.cache.write("ark_webhook:#{key}", true, expires_in: 24.hours)
  end

  def process_payload(payload)
    case payload['status']
    when 'Sent'
      handle_sent(payload)
    when 'HardFail'
      handle_hard_fail(payload)
    when 'SoftFail'
      # Ark retries automatically
      Rails.logger.info "Soft fail: #{payload['classification']}"
    when 'Held'
      handle_held(payload)
    end

    handle_bounce(payload) if payload['original_message']

    if payload['ip_address']
      payload['url'] ? handle_click(payload) : handle_open(payload)
    end
  end

  def handle_hard_fail(payload)
    recipient = payload.dig('message', 'to')

    case payload['classification']
    when 'invalid_recipient', 'inactive_mailbox', 'invalid_domain'
      update_contact_status(recipient, :invalid)
    when 'spam_block', 'policy_rejection'
      DeliverabilityAlert.notify(payload)
    end
  end
end

package main

import (
    "encoding/json"
    "fmt"
    "net/http"
    "sync"
)

type WebhookPayload struct {
    Message struct {
        Token string `json:"token"`
        To    string `json:"to"`
    } `json:"message"`
    Status           string `json:"status"`
    Classification   string `json:"classification"`
    OriginalMessage  *json.RawMessage `json:"original_message,omitempty"`
    IPAddress        string `json:"ip_address,omitempty"`
    URL              string `json:"url,omitempty"`
}

var (
    processed = make(map[string]bool)
    mu        sync.RWMutex
)

func webhookHandler(w http.ResponseWriter, r *http.Request) {
    // 1. Verify signature (see Security page)
    if err := verifySignature(r); err != nil {
        http.Error(w, "Unauthorized", http.StatusUnauthorized)
        return
    }

    var payload WebhookPayload
    if err := json.NewDecoder(r.Body).Decode(&payload); err != nil {
        http.Error(w, "Bad request", http.StatusBadRequest)
        return
    }

    // 2. Idempotency: prevent duplicate processing
    key := fmt.Sprintf("%s_%s", payload.Message.Token, payload.Status)
    mu.RLock()
    if processed[key] {
        mu.RUnlock()
        w.WriteHeader(http.StatusOK)
        return
    }
    mu.RUnlock()

    mu.Lock()
    processed[key] = true
    mu.Unlock()

    // 3. Process based on status (queue to background job in production)
    switch payload.Status {
    case "Sent":
        handleSent(payload)
    case "HardFail":
        handleHardFail(payload)
    case "SoftFail":
        // Ark retries automatically
    case "Held":
        handleHeld(payload)
    }

    if payload.OriginalMessage != nil {
        handleBounce(payload)
    }

    if payload.IPAddress != "" {
        if payload.URL != "" {
            handleClick(payload)
        } else {
            handleOpen(payload)
        }
    }

    // 4. Return 200 quickly
    w.WriteHeader(http.StatusOK)
}

func handleHardFail(payload WebhookPayload) {
    switch payload.Classification {
    case "invalid_recipient", "inactive_mailbox", "invalid_domain":
        updateContactStatus(payload.Message.To, "invalid")
    case "spam_block", "policy_rejection":
        alertDeliverabilityTeam(payload)
    }
}

client.webhooks.test(
    webhook_id="wh_abc123",
    event="MessageSent"
)

await client.webhooks.test('wh_abc123', {
  event: 'MessageSent',
});