Webhooks are merchant-defined web services that are invoked when certain events occur during the execution of raisenow web services. They are currently defined and supported for the recurring payment process (aka subscriptions) and transaction state changes (e.g. transaction state changed to final success, error, or canceled). So, use these webhooks to be notified about change events of your transactions.
Interacting with APIs like our web services often suffers from two important problems:
-
There may exist services which do not make an API request, but need to know the response
-
Some events, like delayed payment slip charges and many recurring payment events, are not the result of a direct API request
Webhooks solve these problems by providing the ability to register a URL that will be invoked through an HTTP POST request if the specified event occurs. All relevant information will be included in the POST request.
In case of webhook failures, invocations will be retried. Such failure includes:
-
No response
-
Unsuccessful response status (non 2xx HTTP status code)
-
request integrity violation
-
response integrity violation
-
Request authentication failure
-
Response authentication failure
The retry interval is calculated using an exponential backoff algortihm predefined by us (currently: 2^invocation_count minutes, e.g. first retry after 1 min, second retry after 2 min, 4min, 8min, etc.). We support up to 12 retries. After the last retry an email can be sent. The email content is predefined by us.
Developers and merchant admins can register webhooks via RaiseNow Manager (EPP System):
| Parameter Name | Mandatory/Optional | Description |
|---|---|---|
| URL | mandatory | Max length: 2000 characters. Info about URL max length: http://stackoverflow.com/a/417184 In case this is empty the Webhook configuration is invalid. Invalid Webhooks are not executed and the event may be propagated to a configured fallback notification subscription. |
| Username | optional | The username will be used either for HTTP Basic Authentication or the generation of the Epayment Signature. |
| Password | optional | The password will be used either for HTTP basic Authentication or as a shared secret for the generation of the Epayment Signature. |
| Integrity Check Required | mandatory | If true: send Content-MD5 HTTP header in request (see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html) Note: When a response contains a Content-MD5 header, then the message integrity is verified even if this attribute is false. |
| Security Level | mandatory | 0, 1, 2, 3 or 4 (see the following table) |
| Merchant Config | mandatory | |
| test_mode | mandatory | Test mode Webhook configurations apply to entities (transaction/subscription) that have been created in test_mode. |
| Security Level | Description |
|---|---|
| 0 | No authentication. This security level is only recommended when the webhook recipient uses IP restriction or other strong security measures. |
| 1 | Request contains HTTP Basic Authentication header. HTTP Basic Authentication should be used only over an encrypted communication channel, i.e. when using the HTTPS protocol. |
| 2 | Security Level 1 + the response is expected to contain an X-Epayment-Signature header. If the signature does not match, this webhook invocation is considered to have failed. |
| 3 | Webhook authentication by X-Epayment-Signature header. Request does not contain the HTTP Basic Authentication header but a signature. The webhook recipient can authenticate the request by validating the epayment signature. Authentication information is not transmitted in clear text and therefore this security level can be considered secure over unencrypted communication channels (e.g. HTTP). However the entity body transmitted will not be encrypted when the communication channel is not encrypted. |
| 4 | Security Level 3 + the response is expected to contain an X-Epayment-Signature header. If the signature does not match, this webhook invocation is considered to have failed. |
In a POST request, your stored parameters and the payment parameters are sent to the registered webhook. The following webhooks are available:
| Event Name | Parameters |
|---|---|
| transaction_status_changed_to_final_success transaction_status_changed_to_final_error transaction_status_changed_to_aborted |
event transaction_id (deprecated) epp_transaction_id subscription_id subscription_token created amount merchant_config merchant currency payment_method payment_provider new_status language test_mode success_url cancel_url error_url Futhermore, all transaction details are returned such as parameters from payment provider. |
| subscription_cc_expiry_reminder | If credit card of a recurring payment subscription will expire next month (expiration month is current month + 1), this webhook will be triggered. Parameters: event amount cancel_url charges_count (not available for the subscription_subscribe event) css_url currency epp_transaction_id error_url errorCode errorDetail errorType expm expy immediate_execution interval (recurring_interval with prefix "01 00 ", e.g. “01 00 * * *” for daily execution ) language masked_cc merchant_config merchant_name mobile_mode payment_method payment_provider subscription_token success_url test_mode transaction_id (deprecated) stored_customer_email stored_* (all other stored customer and subscription parameters) |
| subscription_subscribe | Same parameters for all subscription_* webhooks |
| subscription_charged | Same parameters for all subscription_* webhooks |
| subscription_renewed | Same parameters for all subscription_* webhooks |
| subscription_charge_error | Same parameters for all subscription_* webhooks |
| subscription_cancel | Same parameters for all subscription_* webhooks |
In the webhook configuration GUI in RaiseNow Manager, a “Tester” can be expanded when viewing the details of a webhook configuration. This tester allows to manually trigger test webhook invocations with similar parameters as a real webhook invocation.
-
A special parameter "test_invocation=true"is set and sent as one of the POST parameters to denote that a webhook invocation is just a test invocation. Test invocations do not create entries in the webhook invocations list and are not retried upon failure. In any case, the server should respond as it would respond to a real invocation.
-
Note that manual test invocations will originate from RaiseNow Manager and not from EPP Core (like real webhook invocations), therefore the Source IP Address may be different.
Comments
0 comments
Please sign in to leave a comment.