Skip to main content

​
Webhooks Overview

Learn how PayLoco webhooks work, including subscriptions, delivery and retries, signature verification, and where to configure or manage events. Webhooks enable PayLoco to send instant, real-time push notifications to your application when events occur in your PayLoco account. Understanding how webhooks work helps you design reliable integrations.

​
How Webhooks Work

You create a webhook subscription by registering a notification URL and selecting the events you want to receive. When one of those events occurs in your account, PayLoco sends an HTTP POST request with a JSON payload to your URL. Your endpoint must return a 200 status code and the following response body for PayLoco to consider the delivery successful: 
{
  "code": "00000000",
  "message": "Success"
}
Each event has a stable id, so you can safely handle retries and avoid processing the same event twice. For instructions on creating subscriptions and configuring your endpoint, see Listen for Webhook Events. You can also view and re-trigger webhook events in the PayLoco Web App to inspect delivery status (successful, queued, or failed) and redeliver events after downtime or during debugging.

​
Delivery and Reliability

PayLoco treats any response other than a 200 status code with a response body code of 00000000, or a timeout, as a failed delivery and will retry. Retries use an exponential backoff strategy until your endpoint returns 200.
  • Duplicate events. Your endpoint may receive the same event more than once. Implement idempotent processing by tracking the event id in the payload — the id does not change across retries for the same event.
  • Event ordering. PayLoco does not guarantee events are delivered in the order they were generated. Do not rely on delivery order; use the notifyTime field in the payload if ordering is required.

​
Security and Verification

PayLoco signs every webhook request so you can verify that it came from PayLoco and has not been tampered with. The signature is computed as an HMAC using the request timestamp and request body; you compare the computed value against the signature in the request header. Each subscription has its own secret key in the PayLoco Web App. Verifying the signature before parsing or processing the payload is a critical security step. For step-by-step instructions and code examples, see Verify Webhook Signatures. Your webhook endpoint should use HTTPS, and your server must allow traffic from PayLoco’s webhook IP addresses. For the list of IPs for production and sandbox environments, see Listen for Webhook Events.

​
See Also

To set up or manage webhooks, you can: