Webhooks

Webhooks are HTTP callbacks that receive notification messages for asynchronous events.

Registering a webhook

Contact us at biz.support@blink.net to request a webhook. You must provide the endpoint where we should make the request and the type of event to which you wish to subscribe that endpoint.

HTTP Request format

After registering a webhook for an event type, our servers will make an HTTP request to the endpoint specified in the webhook.

HTTP Methods

The requests will always use the POST method.

HTTP Headers

The requests will always contain the Content-Type: application/json header indicating the JSON body format.

Request Body

The requests always have a JSON body, describing the event.

Example

An example of a HTTP request triggered when a donation is created:

POST /recv_blink_webhooks/ HTTP/1.1

Accept-Encoding: gzip, deflate
Accept: */*
Content-Length: 660
Content-Type: application/json

{
  "event": {
    "donation": {
      "amount": {
        "amount": "1.00",
        "amountInSubunits": 100,
        "amountPrecise": 1000000,
        "amountPreciseExponent": 6,
        "currency": "usd"
      },
      "createdAt": "2021-02-16T18:22:55.837995Z",
      "frequency": "month",
      "id": "1",
      "status": "active"
    },
    "merchant": {
      "alias": "MERCHANT",
      "id": "1"
    },
    "timestamp": "2021-02-16T18:23:00.873312Z",
    "type": "donation_created",
    "user": {
      "createdAt": "2021-02-16T18:22:55.268040Z",
      "email": "test_user@blink.network",
      "firstName": "",
      "id": "1",
      "lastName": ""
    }
  },
  "signature": {
    "algorithm": "ed25519",
    "encoding": "base16",
    "publicKey": "5b156ed6f97eabcf922780ebcda35baf721730e751610c9dbb9ad6aacf202318",
    "signature": "5eb739809076594cb9f4b06a2c4aa1a3b1af4a8df6253282986020e78cfb88a19ee7e1ef00c13276769352a561f17b4f50547a67bde5a997e6bf68e245242f03"
  }
}

Retry mechanism

A registered HTTP server handling the requests should respond with a 200 status code to mark successful receipt of the event.

If the response has a different status code or if the requests times out after 10 seconds, the request will be retried a few times in the upcoming hours.

Webhook authentication

To ensure that a notification you received in a webhook endpoint has been sent by Blink, we provide two ways of authentication.

Token based header authentication

During the registration process of the webhook you can choose to enable token based authentication.

If you enabled this option a secret token with be generated and displayed.

The previously displayed token will be sent in the header of every http POST request as the value under the key Blink-Echo-Token.

Signature based authentication

If you have concerns about token based authentication or are unable to store secrets in your application, Blink signs every notification to provide clients with a way of verifying the authenticity of the message.

Every event contains a signature over the json object present under the key event in a canonical form (no whitespace and with object keys sorted lexicographically) and all necessary information to verify the signature under the json key signature.

Example:

"signature": {
  "algorithm": "ed25519",
  "encoding": "base16",
  "publicKey": "7745859AD1E4C2230CFB5BF72F5DCCAA263E8560F6F6673A9FCD8434B92A7896",
  "signature": "3BCC7143161CFD5ABC2210A09768345C3CF89728FD2D834D6F8429FB6AB5FD7240C3AE2E494B936451601ECA9278A344173466FCA1EC2D180421FAB8401AC004"
}

The fields present inside the signature key have the following meaning:

name	type	always present	description
algorithm	String	☑	algorithm used for the digital signature (currently, is always ed25519)
encoding	String	☑	the encoding type of the publicKey and signature fields (currently, is always base16)
publicKey	String	☑	the public key used to sign the notification event, in a format described by encoding
signature	String	☑	the signature over the notification event, in a format described by encoding

To retrieve the list of public keys for each algorithm you can make a http GET request to https://api.blink.net/public_keys/.

This will return a response in the following format:

{
  "keys": [
    {
      "algorithm": "ed25519",
      "publicKey": "7745859AD1E4C2230CFB5BF72F5DCCAA263E8560F6F6673A9FCD8434B92A7896",
      "timestamp": "1534242521342",
      "timestampSignature": "2EDD7143161CFD5ABC2210A09768345C3CF89728FD2D834D6F8429FB6AB5FD7240C3AE2E494B936451601ECA9278A344173466FCA1EC2D180421FAB8401AC004"
    },
  ]
}

The response contains a list of public keys for each algorithm, and a signature over the current timestamp to show that Blink has the private keys associated to each public key.