Webhook events

Silverfin supports a range of webhook events which allow you to track changes in your environment, and can function as a trigger for your own API flows based on such an event.

Currently the Sync API supports the following webhook events:

The endpoint will send a POST request with a JSON payload to a specified target URL. It will always include the webhook, event and company sections. The document section mentioned in the example below is specific to events related to documents.

  {
    "webhook": {
      "id": 1052767529,
      "url": "http://localhost:3001/webhook",
      "events": [
        "sync.requested",
        "sync.company_added",
        "sync.company_removed"
      ],
      "user_id": 554005444,
      "expired_at": null
    },
    "event": "sync.company_added",
    "company": {
      "id":  398393022,
      "name": "Demo Company"
    }
  }

Webhook signature verification

Every request must include two signature headers: X-SF-SIGNATURE-1 and X-SF-SIGNATURE-2. These signatures are generated using your application's webhook_signing_token_1 and webhook_signing_token_2, respectively.

To confirm the authenticity of a request originating from Silverfin, you should compute its Hash-based Message Authentication Code (HMAC) using the SHA-256 digest algorithm, the request's body as data, and a webhook signing token as the key. For instance, in Ruby, you can achieve this as shown below:

OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha256'), WEBHOOK_SIGNING_TOKEN, REQUEST_BODY)

If at least one of the computed signatures matches its respective header, you can consider the request as authentic. Matching with a single signature allows for a seamless rotation of your application's webhook signing tokens.

Retry strategy

When the endpoint doesn't reply with a 2xx code, the post will be retried with an exponential back-off over a total duration of ~48 hours. If after this time the endpoint still doesn't reply with a 2xx code, the webhook subscription will be marked as expired (disabled). Also note that an expired webhook subscription can't be revived, only deleted. To restore its functionality, the subscription will need to be re-created anew.

Throttling

Silverfin does not throttle outbound webhook events. To protect your application from occasional spikes in incoming events, you may wish to build your own solution or use a third-party service.

Timeouts

Silverfin requires the webhook receiving server to reply within a reasonable time. If the server takes too long to respond, the webhook event will be failed and be retried according to the Retry strategy described above. To avoid timeouts, you should defer processing of the payload until the server replies