Notifications

Grateful’s payment platform supports webhook notifications to keep your systems in sync with your payments. When configured, Grateful will send HTTP POST requests to your notification URL whenever a payment’s status changes.

These notifications allow you to:

• Update your internal systems when payments are confirmed, failed, or expired
• Trigger fulfillment processes automatically
• Maintain accurate payment records without polling the API

Configuring Your Notification URL

To receive webhook notifications:

1. Configure a notification URL for your integration in the dashboard settings 
2. Make sure your endpoint is publicly accessible via HTTPS
3. Implement signature verification to validate incoming requests

Security: Verifying Webhook Authenticity

All webhook notifications are signed using your integration’s secret key. You should always verify this signature before processing the notification to ensure it came from Grateful.

How Signature Verification Works

1. Grateful signs the webhook payload using HMAC-SHA256 with your integration secret
2. The signature is sent in the X-Grateful-Signature HTTP header
3. Your server recreates the signature using the same algorithm and secret
4. If the signatures match, the webhook is authentic

Verification Example

import crypto from 'crypto';
 
function isSignatureValid(payload: string, signature: string, gratefulSecret: string) {
  const hmac = crypto.createHmac('sha256', gratefulSecret);
  hmac.update(payload);
 
  return hmac.digest('hex') === signature;
}
 
// In your webhook handler
app.post('/webhooks/grateful', (req, res) => {
  const signature = req.headers['x-grateful-signature'];
  const payload = JSON.stringify(req.body);
 
  if (!isSignatureValid(payload, signature, process.env.GRATEFUL_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
 
  // Process the notification
  const { paymentId, status } = req.body;
  console.log(`Payment ${paymentId} status: ${status}`);
 
  res.status(200).send('OK');
});

Webhook Request Format

POST /your-notification-endpoint
Content-Type: application/json
X-Grateful-Signature: 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

Test Notification Payload

For test notifications sent from the dashboard:

{
  "message": "This is a test notification from Grateful",
  "timestamp": "2023-03-15T14:32:21Z"
}

Payment Notification Payload

For actual payment status updates:

{
  "paymentId": "payment_123456",
  "status": "success"
}

Status Values

Webhook Headers

Best Practices

1. Return quickly: Respond with a 2xx status code within 30 seconds
2. Process asynchronously: Queue events for background processing if needed
3. Handle duplicates: Notifications may be delivered more than once; use paymentId to deduplicate
4. Verify signatures: Always verify the webhook signature before processing
5. Use HTTPS: Ensure your notification endpoint uses HTTPS

Troubleshooting

Notifications not being received

• Verify your endpoint URL is correct and publicly accessible
• Check that your endpoint accepts POST requests
• Ensure your firewall allows incoming requests

Signature verification failing

• Confirm you’re using the correct integration secret
• Ensure you’re verifying against the raw request body (before JSON parsing)
• Check that you’re using SHA256 for the HMAC algorithm