Skip to main content

Webhooks

Unit uses webhooks to notify your application when an event occurs.

Example events: Application denied, Customer created, Transaction created. See Events for the full list.

caution

New event types are continuously added to the platform. It is up to you to decide which events you want to process and how, but your implementation of the event listener must be able to handle new event types without breaking.

When one of those events occurs, an HTTP POST request is sent to the webhook's configured URL, allowing you to act upon it.

info

To avoid sending stale data, the event's payload does not usually include the entire resource. Once you get notified, you may interact directly with the API to acquire additional resource information.


Unit highly recommends that you make your webhook handlers Idempotent, to ensure events are only handled once on your end.

Use Unit's Dashboard or API to create and manage your webhooks.

Unit sends POST requests to your webhook's URL from one of the following IP addresses:

EnvironmentIP Addresses
Sandbox54.81.62.38
35.169.213.205
Production3.209.193.26
54.156.65.95

Please note that these IP addresses are subject to change.

Securing your webhooks#

Ensure your server is only receiving the expected Unit requests.#

Once your server is configured to receive payloads, it'll listen for any payloads sent to the endpoint you configured.

For security reasons, you probably want to verify that the payloads are coming from Unit.

To verify the payloads when creating a webhook you can set up a secret token which Unit will use to sign the payloads.

Setting up your secret token#

You'll need to set up your secret token in two places: Unit dashboard and your server. To set your token in Unit Dashboard:

  1. Navigate to Webhooks on the left side menu.
  2. Click on create and fill up the token field.

Verifying payloads from Unit#

If your secret token is set, Unit will use it to create a hash signature with the entire body of the webhook request.

This hash signature, encoded with base64 is passed along with each request in the headers as X-Unit-Signature.

Unit uses an HMAC SHA1 to compute the hash.

Example of a NodeJS server verifying webhook payload
const express = require('express')var crypto = require('crypto')const app = express()const port = 4000
app.post('/my-webhhok', (request, response) => {  response.send('request passed signature validation...')})
app.use(express.json());app.use(express.urlencoded({    extended: true}));
app.use((request, response, next) => {    var signature = request.header("x-unit-signature")    var hmac = crypto.createHmac('sha1', <your secret>)    hmac.update(JSON.stringify(request.body))
    if(hmac.digest('base64') == signature) {        next()    }    else {        response.status(500).send("Signatures didn't match!")    }  })

app.listen(port, (err) => {  console.log(`server is listening on ${port}`)})

Testing#

To test the Webhook functionality you can use https://webhook.site. This site will let you generate a unique URL to use for your Webhook and then capture incoming requests, allowing you to examine the event's contents.

Another alternative is to use https://ngrok.com which enables you to expose a port on your development machine to the internet.

Create Webhook#

Creates a webhook.

VerbPOST
Urlhttps://api.s.unit.sh/webhooks
Required Scopewebhooks-write
Data Typewebhook

Attributes#

NameTypeDescription
labelstringA label describing the webhook.
urlstringThe URL of the webhook endpoint.
tokenstringThe secret token (see Securing your webhooks).
contentTypestringThe type of content you wish to receive. Either Json or JsonAPI.
Example Request:
curl -X POST 'https://api.s.unit.sh/webhooks'-H 'Content-Type: application/vnd.api+json'-H 'Authorization: Bearer ${TOKEN}'--data-raw '{  "data": {    "type": "webhook",    "attributes": {      "label": "some label",      "url": "https://webhook.site/81ee6b53-fde4-4b7d-85a0-0b6249a4488d",      "token": "MyToken",      "contentType": "Json"    }  }}'

Get by Id#

Get a webhook resource by id.

VerbGET
Urlhttps://api.s.unit.sh/webhooks/{id}
Required Scopewebhooks

Response#

Response is a JSON:API document.

200 OK#

FieldTypeDescription
dataWebhookThe requested resource after the operation was completed.
curl -X GET 'https://api.s.unit.sh/webhooks/10' \-H "Authorization: Bearer ${TOKEN}"

List#

List webhook resources. Paging can be applied.

VerbGET
Urlhttps://api.s.unit.sh/webhooks
Required Scopewebhooks

Query Parameters#

NameTypeDefaultDescription
page[limit]integer100Maximum number of resources that will be returned. Maximum is 1000 resources. See Pagination.
page[offset]integer0Number of resources to skip. See Pagination.
curl -X GET 'https://api.s.unit.sh/webhooks?page[limit]=20&page[offset]=10' \-H "Authorization: Bearer ${TOKEN}"

Response#

Response is a JSON:API document.

200 OK#

FieldTypeDescription
dataArray of WebhookArray of webhook resources.
Example Response:
{  "data": [    {      "type": "webhook",      "id": "1",      "attributes": {        "createdAt": "2021-02-03T08:17:28.010Z",        "label": "111",        "url": "https://webhook.site/81ee6b53-fde4-4b7d-85a0-0b6249a4488c",        "status": "Disabled",        "contentType": "Json",        "token": ""      }    },    {      "type": "webhook",      "id": "2",      "attributes": {        "createdAt": "2021-02-09T14:54:42.612Z",        "label": "some label",        "url": "https://webhook.site/81ee6b53-fde4-4b7d-85a0-0b6249a4488d",        "status": "Enabled",        "contentType": "Json",        "token": "MyToken"      }    }  ]}

Update#

Update a webhook.

VerbPATCH
Urlhttps://api.s.unit.sh/webhooks/:id
Required Scopewebhooks-write

Attributes#

NameTypeDescription
labelstringThe label of the webhook. To modify or add specify the new label.
urlstringThe URL of the webhook endpoint. To modify or add specify the new URL.
contentTypestringThe content type of the webhook. To modify or add specify the new content type.
tokenstringThe secret token of the webhook. To modify or add specify the token.

Response#

Response is a JSON:API document.

200 OK#

FieldTypeDescription
dataWebhookThe requested resource after the operation was completed.
Example Request:
{  "data": {    "type": "webhook",    "attributes": {      "label": "some label",      "contentType": "Json"    }  }}

Enable#

Enable a webhook.

VerbPOST
Urlhttps://api.s.unit.sh/webhooks/:id/enable
Required Scopewebhooks-write

Response#

Response is a JSON:API document.

200 OK#

FieldTypeDescription
dataWebhookThe requested resource after the operation was completed.
curl -X POST 'https://api.s.unit.sh/webhooks/7/enable' \-H "Authorization: Bearer ${TOKEN}"

Disable#

Disable a webhook.

VerbPOST
Urlhttps://api.s.unit.sh/webhooks/:id/disable
Required Scopewebhooks-write

Response#

Response is a JSON:API document.

200 OK#

FieldTypeDescription
dataWebhookThe requested resource after the operation was completed.
curl -X POST 'https://api.s.unit.sh/webhooks/7/disable' \-H "Authorization: Bearer ${TOKEN}"