# Notification webhooks - the notificationUrl

The Payment API sends messages about events during the payment process to the URL specified in the notificationUrl property. The webhook contains the ID of the payment method and its current status. The HTTP method of the webhook request sent by the Payment API is POST.

By examining the statuses, we can infer changes and possible errors in the life cycle of a payment method. Possible statuses are available here: available statuses.

# Structure of the message

# Recurring and One Time payment

Property	Description
id	Payment ID. This can be One Time or Recurring
status	The current status of the payment method
time	The time the webhook was sent, in unix format
reason	Reason for changing status

# Example

{
    "id": 2,
    "status": "declined",
    "time": 1606740386,
    "reason": "The Customer canceled this payment."
}

# Bank card change

Property	Description
changeId	ID of card replacement request
subscriptionId	Payment ID
status	The status of the exchange. Indicates where the process is
paymentStatus	The current status of the payment method
message	Provides information on possible errors

# Example

{
    "changeId": 42,
    "subscriptionId": 12,
    "status": "declined",
    "paymentStatus": "active",
    "message": "The Customer canceled this payment.",
    "time": 1651662894
}

# Webhook authentication

The authentication of webhooks from the Payment API can be most easily implemented by jointly checking the hmac query parameter added to the sent url and the time property in the post payload.

The hmac generation in practice looks like using the WebhookSecretKey* registered during the application registration to generate a string of the sent post payload with the hash_hmac function (sha256 algorithm). If the receiving party, i.e. application, performs the above operation and compares it with the hmac found in the webhook and it matches, then the webhook can come from the Payment API.

In the second half of the authentication, it is also worth checking whether the timestamp stored in the time property in the post payload approximately coincides with the timestamp of the arrival of the webhook. There may be a difference of a few seconds between the time property and the arrival time. Creating the ideal time difference is the task of the application developer.

It is important to note that the timestamp generated by the Payment API when it is sent is generated based on the Etc/UTC (UTC, +0000) time zone!

*If we do not yet have a WebhookSecretKey, we can do so by emailing partnersupport@shoprenter.hu.

# Example HMAC generation

URL	https://example.com/
Post payload (one-line as string without spaces)	{"id":69,"status":"pending","time":1606740386}
WebhookSecretKey	ppmunf3z66qx6c9cpo0klmyq
HMAC hash_hmac('sha256', $payload, $webhookSecretKey);	317a52549acd37817dfdf2d8989c9386b3d448faa6bc2ff597c71eaa37c76ee3
The full url	https://example.com?hmac=317a52549acd37817dfdf2d8989c9386b3d448faa6bc2ff597c71eaa37c76ee3

← Statuses Delete application →