Set-up

1. Identify the events to monitor

2. Create a webhook endpoint function

3. Register and manage your webhook in PaySG

4. Secure your webhooks

1. Identify the events to monitor

Use the PaySG API reference to identify the PaySG events and the Event objects your webhook endpoint service needs to parse.

---

2. Create a webhook endpoint function

To set up a webhook endpoint function that can accept webhook requests with a POST method, you can follow these steps:

1. Create an HTTPS endpoint function that can handle POST requests with a JSON payload consisting of an event object. Webhooks will only be supported for HTTPS endpoints.

2. Ensure that your endpoint function quickly returns a successful status code (2xx) prior to any complex logic that could cause a timeout. For example, you must return a 2xx response before updating your internal system records.

---

3. Register and manage your webhook in PaySG

After testing your webhook endpoint function, you can register the endpoint's accessible URL. Contact us at [e-mail] to do so. Please provide the following fields to allow PaySG to know where to deliver events.

{
    webhook_url: https://<agency-website>/<your-webhook-endpoint> // e-service endpoint
    description: 'Description of the webhook' // optional
    subscribed_events: ['payment.succeeded'] // array of events e-service subscribes to
}

There are no current limits to how many webhooks endpoints you can register with PaySG. Registered webhook endpoints must be publicly accessible HTTPS URLs. To register your webhook endpoint, provide the publicly accessible HTTPS URL to your endpoint, and a list of events that you will be receiving in your endpoint along with an optional description.

Webhook URL format

The URL format to register a webhook endpoint is:

https://<agency-website>/<your-webhook-endpoint>

For example, if your domain is https://agency-eservice.com and the route to your webhook endpoint is @app.route('/paysg_webhooks', methods=['POST']), specify https://agency-eservice.com/paysg_webhooks as the endpoint URL.

Manage a webhook endpoint configuration

To add, update or delete existing webhook endpoints, contact the PaySG team to do it for you.

4. Secure your webhooks

After confirming that your webhook endpoint connection works as expected, secure the connection by implementing webhook best practices.

One especially important best practice is to use webhook signatures to verify that PaySG generated a webhook request and that it did not come from a server acting like PaySG. The steps to validate PaySG's webhook signature can be found under webhook best practices.

5. Network whitelisting (optional)

PaySG recommends that you verify authenticity of webhooks via signature validation. However, if your system requires IP whitelisting, you can use the following IP addresses.

Staging (https://staging.pay.gov.sg) 13.215.25.150 13.213.93.248

Production (https://pay.gov.sg) 3.1.60.243 13.229.175.148 13.214.75.139

PaySG will inform you at least 1 month in advance of any changes to these IPs.