Skip to main content

best-practices

Webhook Best Practices​

1. Respond Quickly​

  • Return 200 OK as soon as you receive the webhook
  • Process the event asynchronously if needed
  • Timeout is 30 seconds - respond faster to avoid retries

2. Handle Duplicates​

  • Webhooks may be delivered more than once
  • Use the webhook ID (X-WePay-Webhook-Id) to deduplicate
  • Make your processing idempotent

3. Verify Signatures​

  • Always verify X-WePay-Signature before processing
  • Reject unsigned or incorrectly signed requests
  • Use constant-time comparison functions

4. Use HTTPS​

  • Your webhook URL must use HTTPS in production
  • Ensure your SSL certificate is valid and not expired

5. Log Everything​

  • Log all received webhooks for debugging
  • Log signature verification results
  • Keep logs for troubleshooting failed deliveries

6. Do Not Assume Event Order​

  • Dispute resolution sends dispute.resolved, contract.disput.resolved or milestone.disput.resolved, and a refund or release webhook together
  • Apply each delivery by event, disputeId, and milestoneId when it is present
  • Read the refunded or released amount from the refund or release webhook. amount on *.disput.resolved is 0

7. Monitor Your Endpoint​

  • Check delivery logs regularly via /apps/api/webhooks/logs
  • Set up alerts for consecutive failures
  • Test your endpoint periodically using /apps/api/webhooks/test