Webhooks

Receive real-time notifications when events occur in SoapBox.

How Webhooks Work

When an event occurs (like a new prayer request or event registration), we send an HTTP POST request to your configured endpoint with the event details.

Setting Up Webhooks

1. Go to your app in the Dashboard
2. Navigate to the Webhooks section
3. Add your endpoint URL
4. Select the events you want to receive
5. Save your webhook

Webhook Payload

{
  "id": "evt_abc123",
  "type": "prayer.created",
  "timestamp": "2024-03-10T15:30:00Z",
  "data": {
    "id": 456,
    "communityId": 123,
    "content": "Please pray for...",
    "isAnonymous": false,
    "createdAt": "2024-03-10T15:30:00Z"
  }
}

Available Events

Events

Prayers

Donations

Users

Groups

Verifying Webhooks

All webhooks include a signature in the X-SoapBox-Signature header. Verify this signature to ensure the webhook is from SoapBox.

import { Webhooks } from '@soapbox/sdk';

const webhooks = new Webhooks({
  secret: 'your-webhook-secret'
});

// Express.js example
app.post('/webhooks/soapbox', async (req, res) => {
  const signature = req.headers['x-soapbox-signature'];
  const isValid = await webhooks.verify(req.rawBody, signature);

  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }

  const payload = webhooks.parse(req.body);

  switch (payload.type) {
    case 'prayer.created':
      console.log('New prayer:', payload.data);
      break;
    case 'event.registration':
      console.log('New registration:', payload.data);
      break;
  }

  res.status(200).send('OK');
});

Retry Policy

If your endpoint doesn't respond with a 2xx status code, we'll retry:

• 1st retry: 1 minute after initial attempt
• 2nd retry: 5 minutes after 1st retry
• 3rd retry: 30 minutes after 2nd retry
• Final retry: 2 hours after 3rd retry

After 4 failed attempts, the webhook is marked as failed and you'll receive an email notification.

Best Practices

• Respond quickly - Return 200 immediately, process async
• Handle duplicates - Use the event ID for idempotency
• Verify signatures - Always validate the webhook signature
• Use HTTPS - Only HTTPS endpoints are supported

Testing Webhooks

Use the "Test" button in your dashboard to send a test webhook to your endpoint. You can also use tools like webhook.site for testing.