Webhooks and events

# The answer carries the endpoint's signing secret once: store it.
curl --fail-with-body -sS https://api.alura.io/v1/webhooks \
  -H "Authorization: Bearer $ALURA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9b2f4c1e-7a3d-4e8b-b6c5-1d0e2f3a4b5c" \
  -d '{"url": "https://example.com/alura/webhooks", "event_types": ["order.*"], "description": "Order notifications"}'

interface Endpoint {
  id: string;
  url: string;
  event_types: string[];
  status: string;
  secret: string;
}

const res = await fetch('https://api.alura.io/v1/webhooks', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.ALURA_API_KEY}`,
    'Content-Type': 'application/json',
    // A fresh UUID for each new endpoint. Reuse it only to retry this same request.
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({ url: 'https://example.com/alura/webhooks', event_types: ['order.*'], description: 'Order notifications' }),
});
if (!res.ok) throw new Error(`${res.status}: ${await res.text()}`);
const endpoint = (await res.json()) as Endpoint;

console.log(`${endpoint.id} (${endpoint.status}): ${endpoint.event_types.join(', ')} to ${endpoint.url}`);
// Shown once: keep it in your secret store, next to the code that verifies deliveries.
console.log(`secret starts ${endpoint.secret.slice(0, 6)}`);

import json
import os
import urllib.request
import uuid

body = {"url": "https://example.com/alura/webhooks", "event_types": ["order.*"], "description": "Order notifications"}
request = urllib.request.Request(
    "https://api.alura.io/v1/webhooks",
    method="POST",
    data=json.dumps(body).encode(),
    headers={
        "Authorization": f"Bearer {os.environ['ALURA_API_KEY']}",
        "Content-Type": "application/json",
        # A fresh UUID for each new endpoint. Reuse it only to retry this same request.
        "Idempotency-Key": str(uuid.uuid4()),
    },
)
with urllib.request.urlopen(request) as response:
    endpoint = json.load(response)

print(f"{endpoint['id']} ({endpoint['status']}): {', '.join(endpoint['event_types'])} to {endpoint['url']}")
# Shown once: keep it in your secret store, next to the code that verifies deliveries.
print(f"secret starts {endpoint['secret'][:6]}")

curl --fail-with-body -sS "https://api.alura.io/v1/webhooks/we_01JMOCK0000000000000000000/deliveries" \
  -H "Authorization: Bearer $ALURA_API_KEY"

interface Delivery {
  id: string;
  event_id: string;
  attempt: number;
  status: 'pending' | 'succeeded' | 'failed';
  http_status: number | null;
  error: string | null;
  created_at: string;
  next_attempt_at: string | null;
}

const endpointId = 'we_01JMOCK0000000000000000000';
const res = await fetch(`https://api.alura.io/v1/webhooks/${endpointId}/deliveries`, { headers: { Authorization: `Bearer ${process.env.ALURA_API_KEY}` } });
if (!res.ok) throw new Error(`${res.status}: ${await res.text()}`);
const page = (await res.json()) as { data: Delivery[]; has_more: boolean };

// Newest first: one line per attempt, and the ones still queued.
for (const d of page.data) {
  const answer = d.http_status ?? d.error ?? 'not sent yet';
  console.log(`${d.created_at} ${d.event_id} attempt ${d.attempt}: ${d.status} (${answer})${d.next_attempt_at ? `, next at ${d.next_attempt_at}` : ''}`);
}

import json
import os
import urllib.request

endpoint_id = "we_01JMOCK0000000000000000000"
request = urllib.request.Request(
    f"https://api.alura.io/v1/webhooks/{endpoint_id}/deliveries",
    headers={"Authorization": f"Bearer {os.environ['ALURA_API_KEY']}"},
)
with urllib.request.urlopen(request) as response:
    page = json.load(response)

# Newest first: one line per attempt, and the ones still queued.
for d in page["data"]:
    answer = d["http_status"] or d["error"] or "not sent yet"
    nxt = f", next at {d['next_attempt_at']}" if d["next_attempt_at"] else ""
    print(f"{d['created_at']} {d['event_id']} attempt {d['attempt']}: {d['status']} ({answer}){nxt}")

curl --fail-with-body -sS "https://api.alura.io/v1/events?type=order.*" \
  -H "Authorization: Bearer $ALURA_API_KEY"

interface Event {
  id: string;
  type: string;
  created_at: string;
  shop_id: string;
  data: { event_type: string; resource_url: string; shop_id: number };
}

const res = await fetch('https://api.alura.io/v1/events?type=order.*', { headers: { Authorization: `Bearer ${process.env.ALURA_API_KEY}` } });
if (!res.ok) throw new Error(`${res.status}: ${await res.text()}`);
const page = (await res.json()) as { data: Event[]; has_more: boolean };

// Newest first; `data` is Etsy's payload exactly as Etsy sent it.
for (const event of page.data) console.log(`${event.created_at} ${event.type} shop ${event.shop_id}: ${event.data.resource_url}`);
console.log(page.has_more ? 'more: pass next_cursor as cursor' : 'that is all');

import json
import os
import urllib.request

request = urllib.request.Request(
    "https://api.alura.io/v1/events?type=order.*",
    headers={"Authorization": f"Bearer {os.environ['ALURA_API_KEY']}"},
)
with urllib.request.urlopen(request) as response:
    page = json.load(response)

# Newest first; `data` is Etsy's payload exactly as Etsy sent it.
for event in page["data"]:
    print(f"{event['created_at']} {event['type']} shop {event['shop_id']}: {event['data']['resource_url']}")
print("more: pass next_cursor as cursor" if page["has_more"] else "that is all")