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:
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.
The following PHP script implements a webhook that reads configuration from configuration file parameters.ini and uses EPIK classes to create and send an email message. In this example, this webhook is supposed to be invoked if a customer sets up a recurring payment.
<?php require_once("../php/EPIKDefaultImpl.php"); require_once("../php/lib/swift/swift_required.php"); $epayment = new EPIKDefaultImpl(); $params = $epayment->getParameters("../config/parameters.ini"); $message = $epayment->createNewEmailMessage($params["webhooks"]); $message-> setSubject("hello world"); $message-> setFrom(array("firstname.lastname@example.org" => "John Doe")); $message-> setTo(array("email@example.com" => "Jane Doe")); $body = $_POST["stored_customer_email"]; $message->setBody($body); $message->send();?>
Developers and merchant admins can register webhooks via DDT Manager:
|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)|
|test_mode||mandatory||Test mode Webhook configurations apply to entities (transaction/subscription) that have been created in test_mode.|
|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:
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.
charges_count (not available for the subscription_subscribe event)
interval (recurring_interval with prefix "01 00 ", e.g. “01 00 * * *” for daily execution )
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 DDT 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 DDT Manager and not from EPP Core (like real webhook invocations), therefore the Source IP Address may be different.