Webhooks

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.

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.

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.

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.