All Developer Resources Guides

Webhooks

Michael Engler
Michael Engler The chief of community conversations. Community manager Master (Platinum)
  • Updated

Webhooks are notifications (HTTP callbacks) delivered in real-time to a designated URL on your system. Notifications are triggered by specific events, such as payment completions, refunds, or updates to a transaction state. For any issues, reach out to the help@nomupay.com.

Webhook setup

Follow the steps below to successfully implement webhook notifications into your environment. Before you begin, ensure you have an active account with NomuPay.

Webhook Structure

Overview paragraph on webhook structure and types the audience will see in this section.

Property

typeRequired

Type of the notification sent. Specifies the context in which the notification is generated.

actionConditional

Indicator of status change. This field is relevant only for REGISTRATION type notifications, describing the specific operation that occurred. Examples include

  • CREATED when a registration has been created.
  • UPDATED when a registration has been updated.
  • DELETED when a registration has been deleted.
payloadRequired

Content of the notification in JSON format. This includes all relevant data associated with the notification type, reflecting the data format of the related transaction or event.

Notification Body

"type": [notification_type],
"action": [status],
"payload": [content]
  

Webhook Types

Overview paragraph on webhook structure and types the audience will see in this section.

Payment

when a payment is created or updated in the system.

Registration

when a registration is created or deleted.

Schedule

when a scheduler is created or deleted.

Risk

when a risk transaction is created or updated.

Select Notification Type

Availability

Review key information relating to webhook retries, availability and message queuing when planning and setting up your webhook environment.

  • Near real-time. What does near real-time mean?

  • If we don't receive a response within 30 seconds, the message is considered timed out. It will then be scheduled for retry. If we don't receive a HTTP status code 2xx response, the message is considered as failed. It will then be scheduled for retry.

  • The delivery of the notifications may fail reaching your URL destination. The failed notifications are stored for a limited period of time up to 30 days. They are retried at increasing time intervals until either the message is accepted or the maximum retry period is reached. After 30 days of retrying the failed notifications without success, the transactions can be looked up via the reporting endpoints or the user interface.

    Retry-intervals:

    • 1 minute
    • 2 minutes
    • 4 minutes
    • 8 minutes
    • 15 minutes
    • 30 minutes
    • 1 Hour
    • every day until 30 days have passed since the first attempt.
  • When retrying the failed notifications at the next time interval, if they continue to timeout or fail then we fall into a failing retry pattern. Not all failed notification queued for your URL endpoint are attempted to be delivered. We stop retrying until the next retry interval. We reset the retry interval once we see all messages successfully delivered to your URL endpoint.

  • Every day you would receive an email summarizing the newest 100 failed notifications for the configured URL endpoint. The failed notifications queued for the last 30 days will be purged. You can still get transaction data by using the other platform reporting tools but your saved failed notifications will be lost.

  • There is no guarantee on the order of messages. If you first send request A and then request B, you might retrieve a notification first on B then on A, especially if:

    • The time difference between the messages is smaller than the time it takes us to process them
    • The receiving server was unavailable for that time. Once the server is up again new notifications will arrive in real time, old notifications however would only be resent once they are retried using the retry intervals specified above.
  • Especially in asynchronous workflows, it's possible to receive multiple messages for a final status. Please ensure that once a final rejected or successful transaction status notification is received, any other notifications updates for the same transaction are disregarded.

  • Please make sure that your server configured to receive notifications is able to properly handle the peak-loads that can be caused by the transaction processing on the entities you're listening to.

Security

To ensure the security of information and protect data from fraud attempts, webhook notifications are encrypted using UTF-8 to convert human-readable strings to hexadecimal format, so that only the intended recipient with the decryption key can access the original information; see the encryption details below for further understanding.

  • AES is a symmetric key encryption algorithm widely used for encrypting data.

    AES-256

  • The key is a 64-character-long hexadecimal string unique to each webhook used to encrypt and decrypt notifications.

    000102030405060708090A0B0C0D0E0F000102030405060708090A0B0C0D0E0F
  • GCM is an operation mode for symmetric key cryptographic block ciphers, combining the Counter mode of encryption with Galois mode of authentication.

    GCM

  • In GCM mode, padding is not required because the block cipher is turned into a stream cipher.

  • The IV is provided in the HTTP header as X-Initialization-Vector. It is a nonce (number used once) that ensures that each encryption operation is unique.

    3D575574536D450F71AC76D8
  • Included in the HTTP header as X-Authentication-Tag, this tag is used to check the integrity and authenticity of the data.

    19FDD068C6F383C173D3A906F7BD1D83
  • Both the payload and the IV are encoded in hexadecimal format.

Webhook Encryption Example

{
  Payload: 
  "{\"type\": \"PAYMENT\"}",

  Payload in Hexadecimal (after getting bytes in UTF-8): 
  "7B2274797065223A20225041594D454E54227D",

  Key in Hexadecimal: 
  "000102030405060708090A0B0C0D0E0F000102030405060708090A0B0C0D0E0F",

  Initialization-Vector (Hexadecimal): 
  "3D575574536D450F71AC76D8",

  Authentication-Tag (Hexadecimal): 
  "19FDD068C6F383C173D3A906F7BD1D83",

  Encrypted value in Hexadecimal: 
  "F8E2F759E528CB69375E51DB2AF9B53734E393"
}
  

Decryption

Decryption is the process of converting this encrypted data back into its original form. It’s an essential step in webhook data handling because it allows the receiving system to interpret and utilize the data contained in the payload.

When a webhook event is triggered, the payload is encrypted using a specific encryption algorithm and a secret key. This encrypted payload is then sent to the specified URL. Upon receiving the payload, the server must decrypt it using the same algorithm and secret key that were used for encryption. The decryption process ensures the integrity and confidentiality of the data, making webhooks a secure method for automatic data updates. See examples below for implementing a secret key for decrpyting notifications sent from NomuPay.

Change Language

Was this article helpful?

0 out of 0 found this helpful

Have more questions? Submit a request

Comments

0 comments

Please sign in to leave a comment.