Group Webhooks

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.

Updated 4 months ago


Guide


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.