BuyVerse.ai

Webhooks

Subscribe to platform events and receive signed HTTPS deliveries at your own URL. Failed deliveries are retried, and every attempt is logged so you can inspect it.

Register an endpoint

Create a subscription with an HTTPS URL, the events you want, and optionally a signing secret of 16 to 256 characters.

  • POST/integrations/webhooksCreate a subscription
  • GET/integrations/webhooksList your subscriptions
  • PUT/integrations/webhooks/{id}Change a subscription
  • DELETE/integrations/webhooks/{id}Delete a subscription
  • POST/integrations/webhooks/{id}/testSend a sample event
  • GET/integrations/webhooks/{id}/deliveriesSee every delivery attempt
Request: POST /integrations/webhooks
curl --request POST \
  --url https://api.buyverse.ai/api/v1/integrations/webhooks \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://example.com/hooks/buyverse",
    "events": ["order.created", "payment.received"],
    "secret": "whsec_your_signing_secret"
  }'

Event types

Subscribe to any of these events by name.
order.created
A new order was placed.
order.updated
An order changed state or contents.
order.completed
An order was fulfilled and closed.
order.cancelled
An order was cancelled.
payment.received
A payment was captured for an order.
payment.failed
A payment attempt failed.
inventory.low
A SKU dropped below its reorder threshold.
inventory.updated
Inventory levels changed.
deal.created
A new deal was published.
deal.claimed
A deal was claimed by a buyer.
deal.expired
A deal reached its expiry.
agent.query
An AI agent ran a query against your business over the agent network.
agent.order
An AI agent placed or progressed an order on behalf of a buyer.
booking.created
A service booking was created.
booking.completed
A service booking was completed.
booking.cancelled
A service booking was cancelled.
review.received
A verified review was submitted.
trust_score.updated
A business trust score was recalculated.
integration.synced
A connected integration finished a sync.
integration.error
A connected integration reported an error.

Delivery headers

Each delivery carries the event name, a unique delivery ID, a timestamp and an HMAC signature.

Delivery headers
X-Buyverse-Event: order.created
X-Buyverse-Delivery-Id: whd_01H2M…
X-Buyverse-Timestamp: 1685491200
X-Buyverse-Signature: t=1685491200,v1=5257a86…

Verify the signature

Compute an HMAC-SHA256 of ${timestamp}.${rawBody} with your signing secret and compare it with v1 in the X-Buyverse-Signature header. Compare in constant time, over the raw request bytes.

verify.ts
import { createHmac, timingSafeEqual } from 'node:crypto';

// Stripe-style header: t=<unix_seconds>,v1=<hex_hmac>
// Signed payload: `${timestamp}.${rawBody}` using HMAC-SHA256(secret).
export function verify(secret: string, rawBody: string, header: string): boolean {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  const expected = createHmac('sha256', secret)
    .update(`${parts.t}.${rawBody}`, 'utf8')
    .digest('hex');
  return timingSafeEqual(Buffer.from(expected, 'hex'), Buffer.from(parts.v1, 'hex'));
}

Retries

Answer with a 2xx status within a few seconds. A delivery that fails or times out is retried after each of these delays, in order:

See every attempt with GET /integrations/webhooks/{id}/deliveries.