Webhooks are used to notify your application any time an event happens on your account. An example would be a notification triggered after a customer is subscribed.
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.

Receive a Webhook

You can register the webhook URL form the dashboard's notifications menu: https://www.pelcro.com/admin/settings/account/notifications.
When registering the URL, it must respond with HTTP 200 status code to the POST requests in order to pass the initial validation.
Once you register a webhook URL with Pelcro, we will issue a HTTP POST request to the URL specified every time that event occurs.

Structure of a Webhook

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                                
                        }
                   ]
                }
            ]
        }
      

Checking Webhook 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.

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.

List of Notifications

Below is a list of all notifications we currently send to your configured webhook endpoint. Select a notification 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.

Notification

Trigger/Description

address.created

When a new address record is created and added to an end user's account information.

address.updated

When an existing address record has been updated or modified on an end user's account information.

charge.failed

When 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.refunded

When an end-user's credit card has been credited with a refund via the Pelcro Platform.

charge.succeeded

When an end-user's credit card has been successfully charged.

customer.created

When 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.updated

When 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_reset

When an end-user requests a password reset. This will contain the Password reset token which can be used to reset the password.

invoice.created

When 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_failed

When an invoice payment attempt fails. This could be due to a declined payment or lack of a stored payment method.

invoice.payment_succeeded

When an invoice payment attempt succeeds.

invoice.updated

When an invoice is updated.

newsletter.created

When a newsletter record gets created for an end-user on the Pelcro Platform.

newsletter.updated

When a newsletter record gets updated for an end-user on the Pelcro Platform.

source.canceled

When 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.created

When an end-user's payment source or card is created or added to the Pelcro Platform.

source.expiring

Thirty days before an end-user's card or payment source expires.

source.updated

When an end-user's payment source or card is updated on the Pelcro Platform.

subscription.canceled

When an end-user cancels a subscription.

subscription.created

When an end-user creates a new subscription.

subscription.expired

When a subscription expires. This notification is controlled by the expiry date on the end-user's subscription.

subscription.renewed

When a subscription renews, and a new phase is added to the subscription.

subscription.trial_will_end

Three days before a subscription's trial period is scheduled to end, or when a trial is ended immediately.

subscription.updated

When 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)