Webhooks

Webhooks are used to notify your application any time an event happens on your account. An example would be an event triggered after a customer is created. You can register a webhook endpoint through your admin dashboard. We will notify this URL any time an event happens in your account. When the event occurs, an event object is created which contains all the relevant information about what happened, including the type of the event and the data related to that event.

Configuration

You can register to a webhook URL from the platform settings page, as shown below. Although you can subscribe to all events, this is not a recommended practice, as it will put unnecessary pressure on your server. Rather, configure your webhook to listen to only the events which are required by your integration. Note that you can also subscribe to webhooks via our API.

When registering the URL, it must respond with successful status code (2xx) to the POST requests in order to pass the initial validation.

Once you register a webhook URL with Pelcro, we will issue an HTTP POST request to the URL specified every time that event occurs, and your endpoint is expected to answer in a timely fashion by returning a successful status code (2xx). Any other status code is considered a failure.

Events ordering

The order in which events are delivered to endpoints is not related to the order they were triggered on our system. For example, the logical flow of events triggered while creating a subscription might be the following:

  • subscription.created
  • invoice.created
  • charge.created

Your integration shouldn’t assume delivery of events in the order specified in the example above, and needs to handle processing accordingly.

Statuses

Various circumstances can cause webhook event delivery to enter a specific status. Refer to the table below for information on each status.

Webhook statusDescription
OKThe endpoint returned a successful status code (2xx).
ERR - 3xxThe endpoint attempted to redirect the request to another location, which is not handled and thus is considered a failure.
ERR - 4xxThe endpoint can’t or won’t process the request. This might occur when the server detects an error (400), when it has access restrictions, (401, 403), or when the endpoint URL doesn’t exist (404).
ERR - 5xxThe endpoint encountered an error while processing the request.
ERR - TLSA secure connection could not be established to the endpoint. These errors can be caused by an issue with the SSL/TLS certificate or an intermediate certificate in the destination server’s certificate chain. Performing a SSL server test might help identifying the cause of this error.
ERR - Unable to connectA connection with the endpoint could not be established. This might happen if the endpoint cannot be resolved, or if the destination server did accept the connection in a timely manner (see timeouts section below).
ERR - Timed outThe endpoint did not send back a successful status code (2xx) in a timely manner (see timeouts section below).
ERRAn unspecified, unhandled or unrecognized error occurred.

Timeouts

In order to avoid timeouts, endpoints must quickly return a successful status code (2xx) prior to process the event. In other words, your integration should be built it way it simply acknowledges reception of the event. Handling of the business logic tied to the event itself should be deferred to a sub-system.

For example, imagine you want to perform a series of operations every time an invoice.payment_failed event is received by your endpoint. This might be sending an email to the customer, updating the invoice in your own accounting system, updating metadata to the customer object and cancelling the subscription immediately via our Core API.

Depending on the quality of your code as well as the sub-systems and external vendors you are dependent on to perform these operations, this might result in your endpoint taking more time than it should to send successful status code (2xx), therefore resulting in a timeout.

Refer to the table below for the timeouts currently in place.

DescriptionTimeout
The maximum time for endpoint to accept the connection.5 seconds
The maximum time for your endpoint to return successful status code (2xx)20 seconds

Structure

The webhook contains a payload formatted as JSON and the applicable HTTP headers. Webhook data is sent as JSON in the POST request body which will contain the data relevant to the event that triggered the request.

Below you can find a sample payload that will be sent to the webhook endpoint:

  • Request

    • Headers

        X-Pelcro-Hmac-SHA256: pdvcCMQA5298lNhqp7i52StRjHEKgY7Z77yU+f+lfGQ=
      
    • Body

        {
            "type": "subscription.created",
            "id": "evt_ybR5i5QwSVvoWy28ndD4q6hA",
            "created": 1542034347,
            "data": [
                {
                    "object":[
                        {
                            "object": "subscription",
                            "id": 6807,
                            "user_id": 40864,
                            "plan_id": 386,
                            "cancel_at_period_end": null,
                            "canceled_at": null,
                            "current_period_end": null,
                            "current_period_start": null                                
                        }
                   ]
                }
            ]
        }
      

Signatures

Pelcro signs the webhook events it sends to the specified endpoints.

We do so by including a signature in each event’s X-Pelcro-Hmac-SHA256 header. This allows you to validate that the events were sent by Pelcro, not by a third party. Pelcro generates signatures using a hash-based message authentication code (HMAC) with SHA-256.

To verify the signature, you need to:

Step 1: Extract the signature from the header.

The signature can be extracted from the X-Pelcro-Hmac-SHA256 header. Please note that the signature is encoded with MIME base64.

Step 2: Determine the expected signature.

To achieve this you need to compute an HMAC with the SHA256 hash function. Use the endpoint’s signing secret as the key, and use the JSON payload (the request’s body) as the message.

This is a PHP example for the step 2:
base64_encode(hash_hmac('sha256', JSON_PAYLOAD , THE_WEBHOOK_SECRET, true))

Step 3: Compare signatures.

You can compare the generated signature with the signature extracted from the request header.

Step 4: Responding to a webhook

To acknowledge receipt of a webhook, your endpoint should return a 2xx HTTP status code. All response codes outside this range, including 3xx codes, will indicate to Pelcro that you did not receive the webhook. Pelcro will retry the request 5 times in the case of failure.

Events

Below is a list of all events we currently send to your configured webhook endpoint. Select an event to see an example of the excepted JSON payload. Please note that we may change, delete, or add more at any time. While developing and maintaining your code, keep an eye on the changelog.

EventTrigger/Description
address.createdWhen a new address record is created and added to an end user's account information.
address.updatedWhen an existing address record has been updated or modified on an end user's account information.
campaign.triggeredWhen a campaign with a notification action has started processing its action.
charge.failedWhen an end-user's credit card has failed upon submitting a charge. This could be due to insufficient funds on the card or an expired card.
charge.refundedWhen an end-user's credit card has been credited with a refund via the Pelcro Platform.
charge.succeededWhen an end-user's credit card has been successfully charged.
customer.createdWhen an end-user registers via the Pelcro Platform, and a user record has been created with a unique email address, password and customer ID associated to it.
customer.updatedWhen an end-user's information gets updated or modified via the Pelcro Platform (e.g. first or last name, company, or title information).
customer.password_resetWhen an end-user requests a password reset. This will contain the Password reset token which can be used to reset the password.
customer.password_update.succeededWhen a customer successfully updates their password.
customer.email_verification_requestWhen a customer creates a new account and they are requested to verify their email.
customer.email_verification_succeededWhen a customer successfully verifies their email.
customer.passwordless_login_requestWhen a customer requests to login via Passwordless Login
invoice.createdWhen an invoice is created. (e.g. when a subscription is created, when a new future phase starts or when the billing cycle changes on a subscription).
invoice.payment_action_requiredWhen an invoice payment attempt requires further end-user action to complete.
invoice.payment_failedWhen an invoice payment attempt fails. This could be due to a declined payment or lack of a stored payment method.
invoice.payment_succeededWhen an invoice payment attempt succeeds.
invoice.upcomingWhen the configured number of days before a subscription is scheduled to create an invoice is reached.
invoice.updatedWhen an invoice is updated.
member.activatedWhen a member activates their membership under a certain subscription that they have been invited to.
member.createdWhen a member is invited to be a member under a subscription.
member.removedWhen a member is removed from a subscription.
newsletter.createdWhen a newsletter record gets created for an end-user on the Pelcro Platform.
newsletter.updatedWhen a newsletter record gets updated for an end-user on the Pelcro Platform.
order.createdWhen a new e-commerce order gets created for the end-user on the Pelcro Platform or the SDK.
source.canceledWhen an end-user's card expires. This event can be used to inform the client that their Payment source expired and that they need to update it.
source.createdWhen an end-user's payment source or card is created or added to the Pelcro Platform.
source.expiringThirty days before an end-user's card or payment source expires.
source.updatedWhen an end-user's payment source or card is updated on the Pelcro Platform.
subscription.canceledWhen an end-user cancels a subscription.
subscription.changedWhen an end-user's subscription is changed.
subscription.createdWhen an end-user creates a new subscription.
subscription.expiredWhen a subscription expires. This event is controlled by the expiry date on the end-user's subscription.
subscription.gift_notificationWhen it's time to send a notification to the gift recipient, according to the gift date which has been set on the gift subscription during it's creation.
subscription.renewedWhen a subscription renews, and a new phase is added to the subscription.
subscription.trial_will_endThree days before a subscription's trial period is scheduled to end, or when a trial is ended immediately.
subscription.updatedWhen a subscription is updated, or transitions from one status to another (e.g. a subscription gets renewed, a subscription is updated from the platform, a change in the subscription billing cycle)

Security

For added security, your integration should make sure the events it receives originate from Pelcro's infrastructure. See the list of outgoing IP addresses to whitelist.