Developers
Webhooks

Webhooks

1ly can send webhooks when paid API purchases complete. Use these to trigger fulfillment, log usage, or update your systems.

Events

purchase.confirmed

Sent when a paid API link purchase is confirmed.

Payload:

{
  "event": "purchase.confirmed",
  "purchaseId": "uuid",
  "linkId": "uuid",
  "linkSlug": "your-link-slug",
  "linkTitle": "Your API",
  "amount": "0.10",
  "currency": "USDC",
  "buyerWallet": "wallet-or-null",
  "txHash": "transaction-hash",
  "timestamp": "2026-02-05T12:34:56.000Z"
}

Signature Verification

Every webhook includes HMAC headers so you can verify authenticity.

Headers:

  • X-1LY-Signature — HMAC SHA256 of the JSON payload
  • X-1LY-Key-Prefix — API key prefix to identify which key to verify with
  • X-1LY-Event
  • X-1LY-Timestamp

Signing secret:
Use your API key as the HMAC secret.

Verification Example (Node.js)

import crypto from "crypto";
 
export function verify1lyWebhook({ payload, signature, apiKey }) {
  const expected = crypto
    .createHmac("sha256", apiKey)
    .update(JSON.stringify(payload))
    .digest("hex");
 
  if (signature.length !== expected.length) return false;
 
  const sigHmac = crypto.createHmac("sha256", "webhook-verify").update(signature).digest("hex");
  const expectedHmac = crypto.createHmac("sha256", "webhook-verify").update(expected).digest("hex");
 
  return sigHmac === expectedHmac;
}

Enable Webhooks

Add webhookUrl when creating a link:

{
  "title": "My API",
  "url": "https://api.example.com",
  "price": "0.10",
  "webhookUrl": "https://example.com/webhooks/1ly"
}

If your store was created before webhooks, create a new API key before using webhookUrl.

MCP Server1ly SDK