Webhooks

Overview

Webhooks notify your application when events occur in soft.house. Configure an endpoint URL and we’ll send HTTP POST requests with event data.

Setting Up Webhooks

1. Create a Webhook Endpoint

Add an endpoint in your Dashboard (self-service coming v0.2; email developers@soft.house to configure webhooks in the interim):

https://your-app.com/webhooks/soft-house

2. Select Events

Choose which events to receive:

Event	Description
wish.created	New wish created
wish.updated	Wish status changed
wish.fulfilled	Wish successfully completed
mandate.created	New mandate issued
mandate.expired	Mandate expired
payment.succeeded	Payment completed
payment.failed	Payment failed

3. Verify Signatures

All webhooks include an HMAC signature for verification:

import crypto from 'crypto';

function verifyWebhook(payload: string, signature: string, secret: string): boolean {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Webhook Payload

{
  "id": "evt_abc123",
  "type": "wish.fulfilled",
  "created_at": "2026-01-20T10:35:00Z",
  "data": {
    "id": "wish_abc123",
    "status": "fulfilled",
    "query": "Find me a laptop"
  }
}

Retry Policy

Failed deliveries are retried with exponential backoff:

Attempt	Delay
1	Immediate
2	5 minutes
3	30 minutes
4	2 hours
5	24 hours

After 5 failed attempts, the webhook is disabled and you’ll receive an email notification.

Best Practices

• Always verify webhook signatures before processing
• Return 200 status quickly; process events asynchronously
• Handle duplicate deliveries (use event id for deduplication)
• Set up monitoring for webhook failures