Subscribe to webhook events

To subscribe to webhook events, you need to have an endpoint that will receive the webhook events. This endpoint should be capable of handling POST requests and processing the incoming webhook data. Ensure that your endpoint is secure, reliable, and can handle the expected volume of webhook events.

Here's what you need to do:

1. Set up a publicly accessible HTTPS endpoint on your server.
2. Configure your endpoint to accept POST requests.
3. Implement logic to validate and process the incoming webhook data.
4. Use the API call below to register your endpoint URL with our system.

Once subscribed, your endpoint will receive real-time notifications about payment status changes.

Endpoint POST

/api/event-subscriptions/payment.status.changed

headers

'Content-Type: application/json'
'Accept: application/json'

Body parameter

{
  "url": "https://example.com/endpoint",
  "merchant_id": "your_merchant_id"
}

Make sure to replace https://example.com/endpoint with the actual URL where you want to receive the webhook events.

HTTP Code sample

cURLPHPJavaScript

1curl --location --request POST 'https://api-gateway-sandbox.huch.tech/api/event-subscriptions/payment.status.changed' \
2  --header 'Content-Type: application/json' \
3  --header 'Accept: application/json' \
4  --header 'Authorization: Bearer ' \
5  --data-raw '{
6    "url": "https://example.com/endpoint",
7    "merchant_id": ""
8  }'
9

200 response

{
  "event_subscription_id": "1e3fb618-9aeb-445a-bc23-01d2a9c9dcc3",
  "merchant_id": "9981608a-3804-4535-b66b-54c27717be70",
  "event_type": "payment.status.changed",
  "url": "https://example.com/endpoint"
}

When you receive a 200 response, it means that your endpoint has been successfully subscribed to the webhook events.

After successful subscription, you will start receiving webhook events at the endpoint you specified. These events will contain real-time updates about payment status changes, allowing you to automate your system's responses to these changes.

Here are a few important points to keep in mind:

1. Ensure your endpoint is always available to receive these events.
2. Implement proper error handling and logging in your webhook processing logic.
3. Consider implementing a retry mechanism in case your endpoint is temporarily unavailable.
4. Secure your endpoint to verify that the incoming requests are legitimate webhook events from our system.
5. Process the webhook events asynchronously to avoid blocking your server.

For more information on how to handle webhook events, including the payload structure and best practices, refer to our Webhook Content Example documentation.

Request Body

Field	Type	Required	Description
url	string	Yes	The URL endpoint where webhook events will be sent
merchant_id	string	Yes	The unique identifier of the merchant subscribing to events

Responses

Status	Meaning	Description	Schema
200	OK	Successful operation	EventSubscriptionResponse
400	Bad Request	Invalid Arguments	None
409	Conflict	Event subscription already exists	None
500	Internal Server Error	Internal errors	None

Before going live, make sure your endpoint validates incoming notifications — see Webhook Security for signature verification, timestamp checks and replay protection.