Skip to main content

Create a webhook

An event occurs when the state of an API resource changes. For example, a transaction-created event occurs whenever funds are deposited or withdrawn from a Griffin bank account.

Webhooks notify you when events occur. This guide shows you how to set up, test, and operate a webhook.

Prerequisites​

You will need your organization-webhooks-url and your organization-events-url. These are both returned when you request your organization-url. If you don't have your organization-url yet, check out our getting started guide.

Setting up your webhook​

You can create your webhook via the API, or in the Developers section of the app. You must specify the URL for an HTTPS endpoint. Griffin will send events to this endpoint. 

curl --request POST \
  --url "https://api.griffin.com${ORGANIZATION_WEBHOOKS_URL}" \
  --header 'Authorization: $GRIFFIN_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '
{
  "webhook-destination-url": "https://my-server.com/webhook",
  "webhook-description": "My webhook"
}'

A successful response will contain the following information.

{
    "created-by": "/v0/users/ur.0KuXsz1nRC6ccdhneiat7Q",
    "test-webhook-url": "/v0/webhooks/wh.uM9JDBMFQDmv7azPUMuH-g/actions/test",
    "deactivate-webhook-url": "/v0/webhooks/wh.uM9JDBMFQDmv7azPUMuH-g/actions/deactivate",
    "created-at": "2023-11-01T12:37:12.462Z",
    "webhook-description": "My webhook",
    "webhook-url": "/v0/webhooks/wh.uM9JDBMFQDmv7azPUMuH-g",
    "webhook-destination-url": "https://my-server.com/webhook",
    "webhook-state": "active",
    "organization-url": "/v0/organizations/og.O7bHC_t_Qoy0rNfGqbNmyw"
}

Take note of the test-webhook-url so that you can use it later to test your webhook.

Your webhook automatically subscribes to all events for your organisation. The event type is the resource followed by the change-type.

Testing your webhook​

Send a test event using the API or the app to make sure your webhook is working. You will be able to see your endpoint’s response. 

curl --request POST \
  --url "https://api.griffin.com${TEST_WEBHOOK_URL} \
  --header 'Authorization: $GRIFFIN_API_KEY' \
  --header 'Content-Type: application/json'

Followed by

curl --request GET \
  --url "https://api.griffin.com${TEST_WEBHOOK_URL} \
  --header 'Authorization: $GRIFFIN_API_KEY' \
  --header 'Content-Type: application/json'

Finding events​

We don’t record which events you have received or processed - you should store these yourself. But, you can use our Events API to get a list of all the events that have happened in your organisation.

You can filter results using the created-at field, or you can fetch a specific event-URL.

Event delivery​

Duplicates​

We guarantee we will send every event at least once. This means you may receive the same event more than once. You can use the unique event-url in the body of each event to check for this.

Ordering​

We cannot guarantee the order in which you receive events. It is up to you to make sure your system can process events if they arrive at your endpoint out of order.