Webhooks

curl https://api.beaconbox.eu/api/v1/webhook-endpoints \
-H "Authorization: Bearer $BEACONBOX_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com/hooks/beaconbox"}'

# No event_types: receive everything, including types added later.
endpoint = client.webhook_endpoints.create("https://example.com/hooks/beaconbox")

print(endpoint.secret)  # shown once, like an API key

// No eventTypes: receive everything, including types added later.
$endpoint = $client->webhookEndpoints->create('https://example.com/hooks/beaconbox');

echo $endpoint->secret;  // shown once, like an API key

# Verifying by hand, for a language with no SDK. t and v1 come from the header.
# Split "t=1790000000,v1=abc..." into the two parts first.
T=$(printf '%s' "$SIG_HEADER" | sed 's/.*t=\([0-9]*\).*/\1/')
V1=$(printf '%s' "$SIG_HEADER" | sed 's/.*v1=\([0-9a-f]*\).*/\1/')
BODY=$(cat request-body.json)

EXPECTED=$(printf '%s.%s' "$T" "$BODY" \
| openssl dgst -sha256 -hmac "$BEACONBOX_WEBHOOK_SECRET" -r \
| cut -d' ' -f1)

# Real code compares in constant time and rejects a stale $T as well.
[ "$EXPECTED" = "$V1" ] && echo ok || echo reject

import os
from beaconbox import WebhookEventType, WebhookVerificationError, webhooks


@app.post("/hooks/beaconbox")
async def hook(request):
  try:
      event = webhooks.verify(
          await request.body(),  # the RAW body, byte for byte
          request.headers["X-BeaconBox-Signature"],
          os.environ["BEACONBOX_WEBHOOK_SECRET"],
      )
  except WebhookVerificationError:
      return Response(status_code=400)

  if already_handled(event.id):
      return {"ok": True}

  if event.type == WebhookEventType.MESSAGE_BOUNCED:
      mark_address_bad(event.data["recipient_email"])

  record_handled(event.id)
  return {"ok": True}

use BeaconBox\Enum\WebhookEventType;
use BeaconBox\Exception\WebhookVerificationException;
use BeaconBox\Webhooks;

try {
  $event = Webhooks::verify(
      rawBody: file_get_contents('php://input'),   // the RAW body, byte for byte
      signatureHeader: $_SERVER['HTTP_X_BEACONBOX_SIGNATURE'] ?? '',
      secret: getenv('BEACONBOX_WEBHOOK_SECRET') ?: '',
  );
} catch (WebhookVerificationException) {
  http_response_code(400);
  return;
}

if (alreadyHandled($event->id)) {
  http_response_code(200);
  return;
}

if ($event->type === WebhookEventType::MessageBounced) {
  markAddressBad($event->data['recipient_email']);
}

recordHandled($event->id);
http_response_code(200);

curl https://api.beaconbox.eu/api/v1/webhook-endpoints \
-H "Authorization: Bearer $BEACONBOX_API_KEY" \
| jq '.items[] | {url, disabled, consecutive_failures, last_error}'

for endpoint in client.webhook_endpoints.list():
  if endpoint.disabled:
      alert_ops(f"BeaconBox webhook disabled: {endpoint.url} ({endpoint.last_error})")

foreach ($client->webhookEndpoints->list() as $endpoint) {
  if ($endpoint->disabled) {
      alertOps("BeaconBox webhook disabled: {$endpoint->url} ({$endpoint->lastError})");
  }
}

curl -X POST https://api.beaconbox.eu/api/v1/webhook-endpoints/wep_7k2x9m4qd1/test \
-H "Authorization: Bearer $BEACONBOX_API_KEY"

result = client.webhook_endpoints.test("wep_7k2x9m4qd1")

if not result.delivered:
  print(result.status_code, result.error, f"{result.duration_ms}ms")

$result = $client->webhookEndpoints->test('wep_7k2x9m4qd1');

if (!$result->delivered) {
  echo $result->statusCode, ' ', $result->error, ' ', $result->durationMs, 'ms';
}