Webhooks

curl -X POST https://api.sendora.se/v1/webhooks \
  -H "Authorization: Bearer $SENDORA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.se/hooks/sendora",
  "events": [
    "delivered",
    "bounced",
    "deferred",
    "spam_complaint"
  ]
}'

import { Sendora } from '@sendora/sdk';

const sendora = new Sendora({
  token: process.env.SENDORA_API_TOKEN,
});

const { webhookId, secret } =
  await sendora.webhooks.create({
    url: 'https://example.se/hooks/sendora',
    events: [
      'delivered',
      'bounced',
      'deferred',
      'spam_complaint',
    ],
  });

console.log(webhookId);
console.log(secret); // shown this once: store it beside the token

import os

from sendora import Sendora

sendora = Sendora(os.environ["SENDORA_API_TOKEN"])

webhook = sendora.webhooks.create(
    url="https://example.se/hooks/sendora",
    events=[
        "delivered",
        "bounced",
        "deferred",
        "spam_complaint",
    ],
)

print(webhook.webhook_id)
# Shown this once: store it beside the token.
print(webhook.secret)

# Sendora-Signature: t=<unix seconds>,v1=<hex>[,v1=<hex>]
# One v1 per live secret of the webhook, the newest first; each is
# HMAC-SHA256 with that secret over "<t>.<raw body>".
expected=$(printf '%s.%s' "$T" "$RAW_BODY" | openssl dgst -sha256 -hmac "$SENDORA_WEBHOOK_SECRET" | sed 's/^.* //')

# Compare in constant time in your language, refuse a t more than five minutes from your clock, then parse the body.
# One matching v1 is enough; $V1S holds every v1 of the header, one per line.
printf '%s\n' "$V1S" | grep -qx "$expected" && echo "signed by Sendora"

import { verifyWebhook } from '@sendora/sdk';

/*
 * A route handler for any framework that hands you a Fetch Request:
 * Next.js, Hono, SvelteKit, Cloudflare Workers. With Express or Fastify,
 * keep the raw body and pass it and the header the same way.
 */
export async function POST(
  request: Request,
): Promise<Response> {
  const event = await verifyWebhook({
    secret: process.env.SENDORA_WEBHOOK_SECRET,
    signature: request.headers.get('sendora-signature'),
    body: await request.text(),
  });

  if (event.event === 'bounced' && event.details.hard) {
    console.log(
      `${event.recipient} is undeliverable: ${event.details.classification ?? 'unknown'}`,
    );
  }

  return new Response(null, { status: 204 });
}

import os
from collections.abc import Mapping

from sendora import (
    BouncedEvent,
    WebhookVerificationError,
    verify_webhook,
)


# A handler for any framework: give it the raw body
# exactly as it arrived and the request's headers.
def receive(
    body: bytes, headers: Mapping[str, str]
) -> int:
    # Header names ignore case, and a plain dict does not.
    lowered = {
        name.lower(): value
        for name, value in headers.items()
    }
    try:
        event = verify_webhook(
            body,
            signature=lowered.get("sendora-signature"),
            secret=os.environ["SENDORA_WEBHOOK_SECRET"],
        )
    except WebhookVerificationError:
        return 400

    if (
        isinstance(event, BouncedEvent)
        and event.details.hard
    ):
        print(
            f"{event.recipient} is undeliverable: "
            f"{event.details.classification or 'unknown'}"
        )

    return 204

curl -X POST https://api.sendora.se/v1/webhooks/{webhookId}/secrets \
  -H "Authorization: Bearer $SENDORA_API_TOKEN"

import { Sendora } from '@sendora/sdk';

const sendora = new Sendora({
  token: process.env.SENDORA_API_TOKEN,
});

const rolled = await sendora.webhooks.createSecret(
  '7c1e4d2a-0b9f-4a3e-8d6c-5e2f1a9b8c70',
);

console.log(rolled.secretId, rolled.secret);

import os

from sendora import Sendora

sendora = Sendora(os.environ["SENDORA_API_TOKEN"])

rolled = sendora.webhooks.create_secret(
    "7c1e4d2a-0b9f-4a3e-8d6c-5e2f1a9b8c70"
)

print(rolled.secret_id, rolled.secret)

curl -X DELETE https://api.sendora.se/v1/webhooks/{webhookId}/secrets/{secretId} \
  -H "Authorization: Bearer $SENDORA_API_TOKEN"

import { Sendora } from '@sendora/sdk';

const sendora = new Sendora({
  token: process.env.SENDORA_API_TOKEN,
});

await sendora.webhooks.deleteSecret(
  '7c1e4d2a-0b9f-4a3e-8d6c-5e2f1a9b8c70',
  '4a5b6c7d-8e9f-4a0b-8c1d-2e3f4a5b6c7d',
);

import os

from sendora import Sendora

sendora = Sendora(os.environ["SENDORA_API_TOKEN"])

sendora.webhooks.delete_secret(
    "7c1e4d2a-0b9f-4a3e-8d6c-5e2f1a9b8c70",
    "4a5b6c7d-8e9f-4a0b-8c1d-2e3f4a5b6c7d",
)

curl 'https://api.sendora.se/v1/webhooks/{webhookId}/deliveries?status=dead&limit=50' \
  -H "Authorization: Bearer $SENDORA_API_TOKEN"

import { Sendora } from '@sendora/sdk';

const sendora = new Sendora({
  token: process.env.SENDORA_API_TOKEN,
});

const { deliveries } = await sendora.webhooks.deliveries(
  '7c1e4d2a-0b9f-4a3e-8d6c-5e2f1a9b8c70',
  {
    status: 'dead',
    limit: 50,
  },
);

for (const delivery of deliveries) {
  console.log(
    delivery.deliveryId,
    delivery.event,
    delivery.attempts,
    delivery.lastError,
  );
}

import os

from sendora import Sendora

sendora = Sendora(os.environ["SENDORA_API_TOKEN"])

page = sendora.webhooks.deliveries(
    "7c1e4d2a-0b9f-4a3e-8d6c-5e2f1a9b8c70",
    status="dead",
    limit=50,
)

for delivery in page.deliveries:
    print(
        delivery.delivery_id,
        delivery.event,
        delivery.attempts,
        delivery.last_error,
    )

curl -X DELETE https://api.sendora.se/v1/webhooks/{webhookId} \
  -H "Authorization: Bearer $SENDORA_API_TOKEN"

import { Sendora } from '@sendora/sdk';

const sendora = new Sendora({
  token: process.env.SENDORA_API_TOKEN,
});

await sendora.webhooks.delete(
  '7c1e4d2a-0b9f-4a3e-8d6c-5e2f1a9b8c70',
);

import os

from sendora import Sendora

sendora = Sendora(os.environ["SENDORA_API_TOKEN"])

sendora.webhooks.delete(
    "7c1e4d2a-0b9f-4a3e-8d6c-5e2f1a9b8c70"
)