AuctionEdge Webhooks User Guide

This guide walks you through using the AuctionEdge Webhooks dashboard to subscribe to real-time auction events, monitor deliveries, and troubleshoot failures.

---

Getting Started

Creating an Account

1. Navigate to the signup page and provide your email, name, and password (minimum 8 characters).
2. After signup you are automatically logged in and redirected to the dashboard.
3. Your account is assigned a Customer ID and API Key visible on the dashboard overview.

Logging In

Enter your email and password on the login page. Sessions are valid for 7 days. After expiry you will be redirected to log in again.

---

Dashboard Overview

The overview page shows:

• Customer ID and API Key for reference.
• Summary cards with counts for sandbox subscriptions, production subscriptions, recent deliveries, and dead letters. Click any card to navigate to the corresponding page.
• A Quick Start checklist to get up and running.

Quick Start

1. Go to Subscriptions and add your webhook URL for each event type in the sandbox environment.
2. Trigger test events in sandbox and verify delivery on the Deliveries page.
3. When ready, click Promote to Production to copy your sandbox subscriptions to the production environment.
4. Monitor the Deliveries page and check Dead Letters for any failures.

---

Managing Subscriptions

Navigate to Subscriptions from the sidebar.

Environments

Use the Sandbox and Production tabs to switch between environments.

• Sandbox is for testing. Each sandbox subscription creates its own isolated EventBridge rule.
• Production receives real auction events flowing through the system.

Adding a Subscription

1. Select an Event Type from the dropdown. The dropdown is searchable and lists only the event types your account has been granted by your AuctionEdge representative. If the dropdown is empty, no events have been enabled for your account yet — contact your representative to have them added.
2. Enter the Webhook URL where you want events delivered. This must be an HTTPS endpoint that returns a 2xx status code. If you’ve already configured other subscriptions, the field suggests your existing endpoints as you type (across both sandbox and production) — pick one to reuse it, or type a new URL.
3. Click Save.

You can subscribe to one webhook URL per event type per environment, and the same URL can serve as many event types as you like. Saving again with the same event type updates its URL.

Testing a shared endpoint: If one URL handles several event types, use the Test button on any of that endpoint’s sandbox subscriptions to send a sample of that specific event to the URL.

Deleting a Subscription

Click the delete button next to any subscription in the list. The subscription is removed immediately.

Promoting to Production

When your sandbox subscriptions are tested and working, click Promote to Production on the sandbox tab. This copies all active sandbox subscriptions to production. Existing production subscriptions for the same event types are updated with the sandbox webhook URLs.

Testing Subscriptions

Each sandbox subscription row includes a Test button that sends a signed test event directly to your webhook URL. This lets you verify your endpoint is reachable, correctly validates signatures, and handles the payload format before promoting to production.

How it works

1. Click Test next to any sandbox subscription.
2. The platform generates a realistic dummy payload matching the event type's domain (e.g., asset events include VIN, make, model; account events include display name and status flags).
3. The payload is signed with your signing secret using the same HMAC-SHA256 algorithm used for live deliveries.
4. The event is delivered directly to your webhook URL via HTTP POST — it does not pass through EventBridge or SQS.
5. The result appears inline: OK with the HTTP status code on success, or Failed with the status code on failure.

Test delivery details

• The payload always includes one of your assigned auction IDs in the auction-id field.
• Test deliveries include an X-Webhook-Test: true header so your endpoint can distinguish them from live events.
• The delivery is recorded in the Deliveries page just like a normal delivery, so you can inspect the full payload and response.
• All standard webhook headers are included: X-Webhook-Event, X-Webhook-Timestamp, and X-Webhook-Signature.

---

Monitoring Deliveries

Navigate to Deliveries from the sidebar. This page shows the history of all webhook delivery attempts.

Filtering

Use the environment dropdown to filter by All environments, Sandbox, or Production.

Delivery Table

Each row shows:

Column	Description
Event	The event type (e.g., ae.asset.deal.sold.ams)
Env	Sandbox or Production badge
Status	success, failed, or pending
Attempts	Number of delivery attempts (max 3)
HTTP	The HTTP response status code from your endpoint
Delivered	Timestamp of the last delivery attempt

Viewing Event Details

Click any row to expand it and see:

• Delivery ID — unique identifier for the delivery attempt
• Webhook URL — the endpoint the event was sent to
• Created / Last Attempt — timestamps
• Response Status and Response Body — what your endpoint returned
• Event Payload — the full JSON payload that was delivered, formatted for readability

Click the row again to collapse the detail view.

Pagination

If you have more than 50 deliveries, click Load more at the bottom to fetch the next page.

Retention

Delivery records are retained for 60 days in the dashboard. After 60 days they are archived and no longer visible in the UI.

---

Dead Letter Queue

Navigate to Dead Letters from the sidebar. This page shows events that failed all 3 delivery attempts.

DLQ Table

Column	Description
Event	The event type
Env	Sandbox or Production
Webhook URL	The endpoint that failed to accept delivery
Failure Reason	Error message or HTTP response details
Attempts	Number of attempts made (always 3)
Moved to DLQ	Timestamp when the event was moved to the dead letter queue
Action	Replay button or replayed timestamp

Viewing Event Details

Click any row to expand it and see the full detail view including:

• Delivery ID, Webhook URL, timestamps
• Failure Reason — the full error message (not truncated)
• Event Payload — the complete JSON payload, so you can inspect what was being delivered

Replaying Failed Events

If you've fixed the issue with your endpoint:

• Replay a single event — click the Replay button on that row. The event is re-queued for delivery.
• Replay all — click Replay All at the top of the page to re-queue all unreplayed events at once.

Replayed events are delivered directly to your webhook URL without re-applying auction ID filtering (since the event was already matched to your account on the original delivery attempt).

Once replayed, the row is dimmed and shows the replay timestamp instead of the replay button.

Retention

DLQ records are retained for 60 days, same as deliveries.

---

Settings

Navigate to Settings from the sidebar.

Auction IDs

Your account must have auction IDs assigned to receive events. Auction IDs represent the auction locations you operate (e.g., daanw, cpaa, rckfrd).

• Add an auction ID — type it into the input field and press Enter or click Add.
• Remove an auction ID — click the X button next to it.

---

Verifying Webhook Signatures

Every webhook delivery includes HMAC-SHA256 signature headers so you can verify the request came from AuctionEdge and hasn't been tampered with.

Headers Included

Header	Description
X-Webhook-Signature	sha256=<hex-digest> computed over {timestamp}.{payload}
X-Webhook-Timestamp	Unix epoch seconds when the signature was generated
X-Webhook-Event	The event type (e.g., ae.asset.deal.sold.ams)

Verification Steps

1. Retrieve your signing secret from the dashboard API (GET /signing-secret).
2. Extract the X-Webhook-Timestamp and raw request body.
3. Compute HMAC-SHA256("{timestamp}.{body}") using your signing secret.
4. Compare the hex digest with the value after sha256= in the X-Webhook-Signature header.
5. Optionally, check that the timestamp is within an acceptable window (e.g., 5 minutes) to prevent replay attacks.

Example (Node.js)

const crypto = require('crypto');
const http = require('http');

function verifySignature(secret, timestamp, rawBody, signature) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex');
  return `sha256=${expected}` === signature;
}

// In your webhook handler — use the raw body, not a parsed/re-serialized object:
const server = http.createServer((req, res) => {
  let body = '';
  req.on('data', chunk => { body += chunk; });
  req.on('end', () => {
    const isValid = verifySignature(
      process.env.WEBHOOK_SIGNING_SECRET,
      req.headers['x-webhook-timestamp'],
      body,
      req.headers['x-webhook-signature']
    );

    if (!isValid) {
      res.writeHead(401);
      res.end('Invalid signature');
      return;
    }

    const event = JSON.parse(body);
    // process the event...
    res.writeHead(200);
    res.end();
  });
});

Rotating Your Signing Secret

Call POST /signing-secret/rotate to generate a new signing secret. After rotation, all future deliveries will use the new secret. Update your webhook handler with the new secret promptly to avoid verification failures.

---

Environments

Environment	Purpose	Event Source
Sandbox	Testing and development	Per-subscription EventBridge rules; use the test event publisher to trigger events
Production	Live auction events	Events from the organization-wide EventBridge bus matching ae.* event types

Both environments deliver events through the same pipeline (SQS queue, dispatcher Lambda, retry logic, DLQ). The only difference is the event source.

Retry Behavior

Failed deliveries are retried up to 3 total attempts:

1. Immediate delivery
2. Retry after 5 seconds
3. Retry after 30 seconds

If all 3 attempts fail, the event is moved to the Dead Letter Queue where you can inspect it and replay it once the issue is resolved.

---

Webhook Payload Format

When a webhook event is delivered to your endpoint, it arrives as an HTTP POST with a JSON body. The body is the detail object from the original EventBridge event.

Every event includes an auction-id field identifying the auction location. See the API Reference for the full list of event types and their payload schemas.