Webhook configuration

This topic describes how to use webhooks with the Rebilly API and is aimed at a developer audience. For information on how to configure webhooks in the Rebilly UI, see Webhooks.

Use webhooks to notify your systems when certain events occur and to collect event information. Rebilly sends notifications through HTTP and HTTPS methods to a URL of your choice. To view webhooks operations, see the Webhooks API docs.

Each website that you add to Rebilly can have its own webhook configuration. This includes the URI to which you want to send the webhook, along with optional HTTP basic access authentication details.

Define events

To restrict a webhook to a specific event or event types, use the eventsFilter field. To add more than one event type, set an array of system event types as follows:["gateway-account-requested", "subscription-canceled"]. If you leave the eventsFilter field empty blank all events are active for the webhook.

For a complete list of event types, see Global webhook event types.

Security

Create webhook service credentials for your webhook host.

HTTP basic access authentication through HTTPS is highly recommended. This adds an extra layer of security for your webhook endpoint that can prevent undesired data injection by third parties.

Rebilly webhooks may be sent from these IP addresses. If you use HTTP basic access authentication, Rebilly also sends an authorization header along with the GET, POST, PUT, PATCH, or DELETE request.

The following is an example of a header with HTTP basic access authentication enabled that uses username = rebilly, password = superman:

POST /odt4xsod HTTP/1.1
User-Agent: Rebilly - Push
Host: hookb.in
Content-Type: application/json; charset=utf-8
Content-Length: 478
Connection: close
Authorization: Basic cmViaWxseTpzdXBlcm1hbgo=
Accept-Encoding: gzip, deflate

If you use base64 to decode the value decode(cmViaWxseTpzdXBlcm1hbgo=) you receive rebilly:superman.

Responses

Rebilly expects a HTTP 200 OK response after a successful webhook transmission to your systems. If no response is received within 20 seconds, or the HTTP response code is not 200, the request is considered not sent and be marked for retry. The webhook is sent again automatically after 30 minutes. If no response is received, the webhook is attempted by an exponential back-off, at 1, 2, 4, 8, and 16 hours for a total of 6 retries attempts until successful. If still unsuccessful, it is not attempted again.

Data validity

When a notification is triggered, Rebilly sends all available information to your endpoint at the time of the event. The data contained in the webhook reflects the state of Rebilly records at the time of the event. In the event of a delay, your records might be more up to date than the data that is sent by the webhook.

The following example describes a scenario where a delay occurs in recording of data between systems.

1. A transaction triggers a webhook, and some relating customer information was not supplied at the time when the transaction occurred.
2. The notification transmission is delayed for a short period.
3. Your system modifies or adds this information before a notification is received.
4. The notification for the transaction is received by your systems, but the customer information does not match your records.

Data authenticity

In Rebilly, all outgoing webhooks contain a Security-Signature header. Use this header to ensure data authenticity. Signature verification is optional and is not required for your integration to work, but it is recommended.

The authenticity check uses JSON Web Tokens (JWTs) and JSON Web Keys (JWKs) to verify webhooks.

To authenticate webhook data:

1. Locate, load, and cache Rebilly JWKs from the live or sandbox environments.
   To ensure proper key rotation, Rebilly recommends a cache Time to Live (TTL) of no greater than 1 hour.
2. Extract the JWT from the Security-Signature header of the webhook.
3. Validate the JWT against your preferred JWT and JWK library for your chosen programming language.
4. Decode the payload (second) segment of the JWT and verify the following checks:

• The iss value is equal to the Rebilly API URL where you expect to receive webhooks. For example, https://api.rebilly.com/ or https://api-sandbox.rebilly.com/ .
• The aud value is equal to your organization ID within Rebilly.
• The iat value is greater or equal to the current Unix timestamp. Rebilly recommends a leeway of no greater than 10 seconds.
• The exp value is less than the current Unix timestamp. This is an optional check to prevent replay attacks. Rebilly accepts webhooks that are received within a 5-minute timeframe between the iat and exp values.
• The requestBodyHash is equal to the SHA256 hash of the raw webhook body.
  Authenticity check example

  The following example is of a webhook that is received at 2023-02-12 19:45:00 UTC (formatting and spaces are preserved in the webhook body):

  Copy

  Copied

  POST /odt4xsod HTTP/1.1
  User-Agent: Rebilly - Push
  Host: hookb.in
  Content-Type: application/json; charset=utf-8
  Content-Length: 478
  Connection: close
  Security-Signature: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImI2MDNmMWY4Y2U0Y2RlMzc2NjExNzlkNGRmODNlYjZlODc0ZTRjZjRjNWNmNWRhMGIxYTY0NDUyMDJmNmJlNGIifQ.eyJpc3MiOiJodHRwczovL2FwaS1zYW5kYm94LnJlYmlsbHkuY29tLyIsImF1ZCI6ImE5ZjY4ZTZlLWUyZTYtNDNkZC1hMjdmLTgxMjAxMjFkNzQyOCIsImlhdCI6MTY3NjIzMDk3MiwiZXhwIjoxNjc2MjMxMjcyLCJyZXF1ZXN0Qm9keUhhc2giOiIyMjA1YThkMjU0M2M5N2E5YThkYzI5YTRmOWZkZjcxN2ZkOTQ3OGI5ODkxYWRmNTJhYmQ5YzA5ZjdhZmRlMDk0In0.ChVc_NAWxfZVEl4g7QhFFO8c5ZtUuTWlP60qQ7gEKtUQdWY70WyzYOREbGPodTbraSNggh1M98gaYSqcQM6vAk3op_9HQpeMtQEIGUOjNDMe2_BmwyeGtcc3_c3Ft0gsARUYatZcVCeeYi7i8Xwekj2xQKkxbkLYEkHHj3f_o2dHXdXaFVvgU2fNN9pmfq1iI2ROM_UXrpGDfsm1nfvZsFLk9cdCum3bBMpTeqelm02ojk6yHES9otoMTYqwGJ5ovyOKaPzMAUJT1tNv1xzf5YxxyBMj6CRqTMPkItrgU3nX6pPMdS5cbEWzhTUcm29WeWrXf90PqLUJTvSxIuMhUA
  Accept-Encoding: gzip, deflate
  
  {"dataExportId":"d9dd134f-0bee-46b1-bec0-992da3173336","fileId":"d348968b-41ed-4d7d-b534-02e5265c8912","eventType":"data-export-completed","_embedded":{"dataExport":{"id":"d9dd134f-0bee-46b1-bec0-992da3173336","name":"Preview","resource":"customers","format":"csv","arguments":null,"dateRange":null,"emailNotification":[],"fields":[],"recurring":null,"status":"pending","userId":"3d08e3f3-fa38-4731-9761-8a04400e05d3","recordCount":null,"scheduledTime":"2023-02-12T19:42:52+00:00","expiredTime":"2023-03-12T19:42:52+00:00","purgedTime":"2024-06-12T19:42:52+00:00","createdTime":"2023-02-12T19:42:52+00:00","updatedTime":"2023-02-12T19:42:52+00:00","_links":[{"rel":"self","href":"https:\/\/api-sandbox.rebilly.com\/organizations\/a9f68e6e-e2e6-43dd-a27f-8120121d7428\/experimental\/data-exports\/d9dd134f-0bee-46b1-bec0-992da3173336"},{"rel":"user","href":"https:\/\/api-sandbox.rebilly.com\/users\/3d08e3f3-fa38-4731-9761-8a04400e05d3"}]}},"_links":[{"rel":"dataExport","href":"https:\/\/api-sandbox.rebilly.com\/organizations\/a9f68e6e-e2e6-43dd-a27f-8120121d7428\/experimental\/data-exports\/d9dd134f-0bee-46b1-bec0-992da3173336"},{"rel":"download","href":"https:\/\/api-sandbox.rebilly.com\/organizations\/a9f68e6e-e2e6-43dd-a27f-8120121d7428\/files\/d348968b-41ed-4d7d-b534-02e5265c8912\/download"}]}

  At 2023-02-12 19:45:00 UTC the JWKs located at https://api-sandbox.rebilly.com/.well-known/keys contain the following key:

  Copy

  Copied

  [
      {
          "kty": "RSA",
          "n": "sT66o-HJLpVt5qifPS6MsFpu8dj-NZJWWJnoJMohCBHhGNL8v6EJm_kCNY43Czi0Bt5dbrFovPgcjdR1yq938hQ9Hi2SjNoddqcsvOUtThztsXitTKSutBKjVcInN_At_DxCpO8pardiR3aLR-bCClz8iSutmRaTenee6cMUkkZZRs0XRqI_gDPfAoN_f5HWZBXnu-VSUrBpT-PnzA4ICvR9ZaeU3EK3T64QhLnxuGa_o561__CR5oD79sEXILqJoD47uE22FydAvHvrgWqk0RMkBFtSdgmFkhylpAVgnGWAJqB2FLy-yLh5QMS02SxKtz89KRVRe0V4BVx5x3bTbw",
          "e": "AQAB",
          "alg": "RS256",
          "kid": "b603f1f8ce4cde37661179d4df83eb6e874e4cf4c5cf5da0b1a6445202f6be4b",
          "use": "sig"
      }
  ]

  The JWT signature could be verified with the key whose kid value is b603f1f8ce4cde37661179d4df83eb6e874e4cf4c5cf5da0b1a6445202f6be4b as expected.

  The decoded JWT payload segment provides:

  Copy

  Copied

  {
      "iss": "https://api-sandbox.rebilly.com/",
      "aud": "a9f68e6e-e2e6-43dd-a27f-8120121d7428",
      "iat": 1676230972,
      "exp": 1676231272,
      "requestBodyHash": "2205a8d2543c97a9a8dc29a4f9fdf717fd9478b9891adf52abd9c09f7afde094"
  }

  Results of the verification checks:

  • The iss value is equal to the sandbox API URL.
  • The aud value is equal to the organization ID a9f68e6e-e2e6-43dd-a27f-8120121d7428 .
  • The iat value is equal to 2023-02-12 19:42:52 UTC , which is less than the reception time of 2023-02-12 19:45:00 UTC .
  • The exp value is equal to 2023-02-12 19:47:52 UTC , which is greater than the reception time of 2023-02-12 19:45:00 UTC .
  • The requestBodyHash value is equal to the SHA256 hash of the raw webhook body:

  Copy

  Copied

  sha256('{"dataExportId":"d9dd134f-0bee-46b1-bec0-992da3173336","fileId":"d348968b-41ed-4d7d-b534-02e5265c8912","eventType":"data-export-completed","_embedded":{"dataExport":{"id":"d9dd134f-0bee-46b1-bec0-992da3173336","name":"Preview","resource":"customers","format":"csv","arguments":null,"dateRange":null,"emailNotification":[],"fields":[],"recurring":null,"status":"pending","userId":"3d08e3f3-fa38-4731-9761-8a04400e05d3","recordCount":null,"scheduledTime":"2023-02-12T19:42:52+00:00","expiredTime":"2023-03-12T19:42:52+00:00","purgedTime":"2024-06-12T19:42:52+00:00","createdTime":"2023-02-12T19:42:52+00:00","updatedTime":"2023-02-12T19:42:52+00:00","_links":[{"rel":"self","href":"https:\/\/api-sandbox.rebilly.com\/organizations\/a9f68e6e-e2e6-43dd-a27f-8120121d7428\/experimental\/data-exports\/d9dd134f-0bee-46b1-bec0-992da3173336"},{"rel":"user","href":"https:\/\/api-sandbox.rebilly.com\/users\/3d08e3f3-fa38-4731-9761-8a04400e05d3"}]}},"_links":[{"rel":"dataExport","href":"https:\/\/api-sandbox.rebilly.com\/organizations\/a9f68e6e-e2e6-43dd-a27f-8120121d7428\/experimental\/data-exports\/d9dd134f-0bee-46b1-bec0-992da3173336"},{"rel":"download","href":"https:\/\/api-sandbox.rebilly.com\/organizations\/a9f68e6e-e2e6-43dd-a27f-8120121d7428\/files\/d348968b-41ed-4d7d-b534-02e5265c8912\/download"}]}')

Test webhooks

This process describes how to test webhooks using the Rebilly API.

1. Create webhook credentials for your webhook host.
2. Trigger a test webhook .

Alternatively, use the Rebilly UI to test a webhook.

Example event notification

All events are described in the Rebilly API documentation. For an example, see the Invoice paid event.

For more information on Rebilly resources, see Concepts.