Using Webhooks

Freckle is now Noko! Learn how to migrate your apps here

Not implemented yet!

This is just a sneak peek into how this resource might work. Attempting to call any actions will return a 404 error.

How do Webhooks work?

Webhooks allow your application or integration to be notified of specific events in your Noko account. You can use this to automatically update project estimates, generate summary reports for the time logged every day, integrate your Noko invoices with your bookkeeping software; the possibilities are endless!

Rather than polling for new data or changes, you can subscribe to specific events, and we’ll notify you as soon as they happen!

Once a Webhook has been created, we’ll send POST requests for the events that you’ve subscribed to for that webhook.

How do I create a Webhook?

Supervisor access required

In the current version of Webhooks, you will need supervisor access to Noko in order to use webhooks. This will likely change in the future 😊

To create a webhook, you’ll need:

Which type of setup should I choose?

Webhooks Endpoint (Strongly recommended)
My application will be running in a production environment, I’m writing an integration for Noko in my project, or I want to automate setup.
Creating a webhook from the Webapp
My application is a script or for internal use only.

Creating a Webhook from the API

In order to create a Webhook from the API, you’ll need to have valid API credentials. Using the API to manage your webhooks allows you automatically set up your integration, without requiring a user to copy/paste any URLs, or configure anything else!

Creating a Webhook from the Webapp

You can create a Webhook from the main Noko app by going to the “Webhooks” tab in your “Integrations & Connected Apps” section.

How are Webhooks different than the API?

Webhooks are a way to be notified of changes in your Noko account, while the API is a way to access and interact with your Noko account.

When a Webhook is notified of an event, it will receive an object that matches the way the resource is given in the API. This is so you can reuse the same code between your Webhooks & API actions.

Oftentimes, an integration will use both Webhooks & the API to connect with Noko.

Example: Project Management Tool

Let’s say you have a project management tool that integrates with your Noko account.

What does a Webhook payload look like?

A Webhook payload has the following structure:

Content-Type: application/json
X-Noko-EventCategory: entry
X-Noko-Delivery: 050db47d-20f3-4479-86c3-e7a237f670e5
X-Noko-Signature: 97edbb33123042fb0df0f78eef173123d50b095b769f419a601fbdf40918b8fe
User-Agent: Noko-Webhooks
  "id": "050db47d-20f3-4479-86c3-e7a237f670e5",
  "webhook": {
    "id": 123456,
    "name": "Da Best Noko Webhook"
  "type": "entry.updated",
  "created_at": "2012-01-09T08:33:29Z",
  "object": {
    "id": 1,
    "date": "2012-01-09",
    "user": {
      "id": 5538,
      "email": "[email protected]",
      "first_name": "John",
      "last_name": "Test",
      "profile_image_url": "",
      "url": ""
    "billable": true,
    "minutes": 60,
    "description": "noko",
    "project": {
      "id": 37396,
      "name": "Gear GmbH",
      "billing_increment": 10,
      "enabled": true,
      "billable": true,
      "color": "#ff9898",
      "url": ""
    "tags": [
        "id": 249397,
        "name": "noko",
        "billable": true,
        "formatted_name": "#noko",
        "url": ""
    "source_url": "",
    "invoiced_at": "2012-01-10T08:33:29Z",
    "invoice": {
      "id": 12345678,
      "reference": "AA001",
      "invoice_date": "2013-07-09",
      "state": "unpaid",
      "total_amount": 189.33,
      "url": ""
    "import": {
      "id": 8910,
      "url": ""
    "approved_at": "2012-01-10T08:33:29Z",
    "approved_by": {
      "id": 5538,
      "email": "[email protected]",
      "first_name": "John",
      "last_name": "Test",
      "profile_image_url": "",
      "url": ""
    "url": "",
    "invoiced_outside_of_noko_url": "",
    "approved_url": "",
    "unapproved_url": "",
    "created_at": "2012-01-09T08:33:29Z",
    "updated_at": "2012-01-09T08:33:29Z"

Verifying a Webhook payload

A secret key is automatically generated when a webhook is created, make sure you store this signature when you create your webhook! (but you can always re-roll the signature if you need to). We use this secret to generate a signature for each webhook payload, so you can verify that the request came from Noko. This signature is stored in the X-Noko-Signature request header.

To verify the signature:

  1. Retrieve the secret value that you stored
  2. Use a SHA 256 HMAC hexdigest to compute the hash, using the secret as the key.
  3. Compare your generated signature with the one in X-Noko-Signature.

Make sure to use a secure comparison method, like Rack::Utils.secure_compare