API Reference
Webhooks

Webhooks

Webhooks deliver real-time event notifications to your server. When SDK events are ingested that match a webhook's configured event types, AgentWallie sends an HTTP POST to your webhook URL.

Create a Webhook

POST /v1/projects/:id/webhooks

Request Body

FieldTypeRequiredDescription
urlstringYesHTTPS URL to receive webhook payloads
eventsstringYesComma-separated event names to subscribe to
secretstringNoHMAC signing secret (auto-generated if omitted)
activebooleanNoWhether the webhook is active. Default: true

Example

curl -X POST https://agentwallie.com/api/v1/projects/PROJECT_ID/webhooks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_your_private_key" \
  -d '{
    "url": "https://api.yourapp.com/webhooks/agentwallie",
    "events": "transaction_complete,transaction_fail",
    "active": true
  }'

Response 201 Created

{
  "id": "wh_abc123",
  "projectId": "PROJECT_ID",
  "url": "https://api.yourapp.com/webhooks/agentwallie",
  "events": "transaction_complete,transaction_fail",
  "secret": "a1b2c3d4e5f6...hex_string...",
  "active": true,
  "createdAt": "2025-03-15T10:00:00.000Z"
}
⚠️

Save the secret value. You need it to verify webhook signatures. If you did not provide one, the auto-generated secret is only returned on creation.

List Webhooks

GET /v1/projects/:id/webhooks
curl https://agentwallie.com/api/v1/projects/PROJECT_ID/webhooks \
  -H "Authorization: Bearer sk_your_private_key"

Update a Webhook

PUT /v1/projects/:id/webhooks/:wid

Request Body

All fields optional:

FieldTypeDescription
urlstringNew webhook URL
eventsstringUpdated event list
secretstringNew signing secret
activebooleanEnable/disable
curl -X PUT https://agentwallie.com/api/v1/projects/PROJECT_ID/webhooks/wh_abc123 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_your_private_key" \
  -d '{"active": false}'

Delete a Webhook

DELETE /v1/projects/:id/webhooks/:wid
curl -X DELETE https://agentwallie.com/api/v1/projects/PROJECT_ID/webhooks/wh_abc123 \
  -H "Authorization: Bearer sk_your_private_key"

Response: 204 No Content

HMAC Signature Verification

Every webhook delivery includes an X-AgentWallie-Signature header containing an HMAC-SHA256 signature of the request body, signed with the webhook's secret.

Verification Example (Node.js)

const crypto = require('crypto');
 
function verifyWebhook(body, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(body))
    .digest('hex');
 
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}
 
// In your webhook handler:
app.post('/webhooks/agentwallie', (req, res) => {
  const signature = req.headers['x-agentwallie-signature'];
  const isValid = verifyWebhook(req.body, signature, 'your_webhook_secret');
 
  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }
 
  // Process the webhook
  const { events } = req.body;
  // ...
 
  res.status(200).send('OK');
});

Webhook Event Types

You can subscribe to any standard SDK event name:

EventDescription
paywall_openA paywall was presented
paywall_closeA paywall was dismissed
purchase_startedUser initiated a purchase
transaction_completePurchase completed
transaction_failPurchase failed
restore_startedRestore initiated
restore_completeRestore completed
placement_triggeredA placement was evaluated

Custom event names are also supported -- subscribe to any event name your app tracks.

Receipts & SubscriptionsAgent Features