> For the complete documentation index, see [llms.txt](https://docs.xplorpay.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.xplorpay.com/api-reference/webhooks/register-url.md).

# Register URL

To register your webhook URL, send the endpoint details to the integration team. They complete the registration and confirm when your endpoint is configured.

{% hint style="warning" %}
Ensure that your endpoint supports HTTPS and can handle requests from the integration team or webhook.
{% endhint %}

### **Secure endpoint** <a href="#secure-your-endpoint" id="secure-your-endpoint"></a>

To secure the endpoint:

* Use an HTTPS endpoint.
* Restrict IP addresses if applicable.

### **Verify your signature** <a href="#verify-your-signature" id="verify-your-signature"></a>

Legacy transaction webhooks include a `signature` field in the header. Verifying this digital signature helps confirm that Xplor Pay sent the notification and that the payload was not modified during transmission.

{% hint style="info" %}
Digital-signature verification applies to legacy transaction webhooks only. Other legacy webhooks do not include signature validation. Enhanced webhooks use optional shared-secret authentication when configured.
{% endhint %}

For more information about authentication methods, see [Webhook Authentication](https://docs.xplorpay.com/api-reference/webhooks/webhook-authentication).

### **Webhook notifications** <a href="#webhook-notifications" id="webhook-notifications"></a>

Once your endpoint is registered and webhooks are configured, you will begin receiving event notifications relevant to your merchant account.

The following example shows a webhook notification:

{% code lineNumbers="true" %}

```json
{
  "event": "Manual Review",
  "merchantId": "6588949900000011",
  "payload": null
}
```

{% endcode %}

{% hint style="warning" %}
The `payload` value varies by event type. Some events return `null`, while others include additional JSON data relevant to the event.
{% endhint %}

### **Retry logic** <a href="#retry-logic" id="retry-logic"></a>

If your endpoint does not acknowledge receipt of a webhook (that means, returns a `non-2xx` status), the system will automatically retry the callback. A `2xx` status code (example, `200 OK`) indicates successful receipt of the webhook, and no retry will be attempted.

`Non-2xx` status codes (example, `400 Bad Request`, `500 Internal Server Error`) indicate failure. The system will retry the request based on the retry policy.

* **Total Attempts:** Up to 3 delivery attempts
* **Retry Strategy:** Exponential backoff is applied between each attempt

This ensures reliable delivery of webhook events, even if your endpoint is temporarily unavailable.

{% hint style="warning" %}
Ensure your server responds with a `200` status code upon successful receipt to avoid missed events.
{% endhint %}

### **Test webhook**

To test your webhook integration, ensure your endpoint returns the appropriate HTTP status code after processing a request. In the INT (integration) environment, the system recognizes special keywords in the merchant's **DBA (Doing Business As)** name field. Use the following naming conventions to simulate specific onboarding outcomes:

* **\[DECL]** – The application will be marked as **Declined** after signing. A webhook will be triggered with the "Declined" status.
* **\[PEND]** – The application will move to **Pended** status after signing. You will receive a webhook indicating this status change.
* **\[APPR]** – The application will be marked as **Approved** after signing, and a corresponding webhook will be sent.

{% hint style="warning" %}
Ensure that the DBA name includes the exact keyword in brackets (example, `MyStore [DECL]`) to trigger the appropriate behavior in the INT environment.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.xplorpay.com/api-reference/webhooks/register-url.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
