Webhooks

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

In Beta!

Webhooks and Broadcasts are in beta while we make sure they're rock solid. The specs are finalized though, so they're safe to add to your integration!

This API allows you to manage your webhooks entirely from the API, so you can set up your integrations automatically without requiring any user configuration.

List Webhooks

Get all webhooks, sorted by the most recently created

GET /v2/webhooks
name
Optional string
Only webhooks containing this text in their name are returned.
Example: name=Notifier
events
Optional string
A comma-separated list of events to filter by.
Example: events=entry.updated,entry.updated.approved
state
Optional string
Only webhooks in this state will be returned. Accepted Values are:
  • enabled
  • disabled

Response

Status: 200 OK
Link: <https://api.nokotime.com/v2/webhooks?page=2>; rel="next",
 <https://api.nokotime.com/v2/webhooks?page=5>; rel="last"
[
  {
    "id": 123456,
    "name": "Da Best Noko Webhook",
    "state": "enabled",
    "events": [
      "entry.created",
      "entry.updated",
      "entry.deleted",
      "entry.updated.approved",
      "entry.updated.unapproved",
      "entry.updated.invoiced",
      "entry.updated.uninvoiced"
    ],
    "payload_uri": "http://dabestnokoapp.com/webhooks/entry_events",
    "url": "https://api.nokotime.com/v2/webhooks/123456",
    "add_events_url": "https://api.nokotime.com/v2/webhooks/123456/add_events",
    "remove_events_url": "https://api.nokotime.com/v2/webhooks/123456/remove_events",
    "reroll_secret_url": "https://api.nokotime.com/v2/webhooks/123456/reroll_secret",
    "enable_url": "https://api.nokotime.com/v2/webhooks/123456/enable",
    "disable_url": "https://api.nokotime.com/v2/webhooks/123456/disable"
  }
]

Get a single Webhook

GET /v2/webhooks/:id

Status: 200 OK
{
  "id": 123456,
  "name": "Da Best Noko Webhook",
  "state": "enabled",
  "events": [
    "entry.created",
    "entry.updated",
    "entry.deleted",
    "entry.updated.approved",
    "entry.updated.unapproved",
    "entry.updated.invoiced",
    "entry.updated.uninvoiced"
  ],
  "payload_uri": "http://dabestnokoapp.com/webhooks/entry_events",
  "url": "https://api.nokotime.com/v2/webhooks/123456",
  "add_events_url": "https://api.nokotime.com/v2/webhooks/123456/add_events",
  "remove_events_url": "https://api.nokotime.com/v2/webhooks/123456/remove_events",
  "reroll_secret_url": "https://api.nokotime.com/v2/webhooks/123456/reroll_secret",
  "enable_url": "https://api.nokotime.com/v2/webhooks/123456/enable",
  "disable_url": "https://api.nokotime.com/v2/webhooks/123456/disable"
}

Create a Webhook

POST /v2/webhooks/

Inputs

name
Required string
The name of the Webhook
payload_uri
Required string
The URI to send the payloads to.
events
Required array of strings
The events this webhook should be subscribed to.
You can also specify '*', which is a wildcard for all current and future events.
{
  "name": "Da Best Noko Webhook",
  "payload_uri": "http://dabestnokoapp.com/webhooks/entry_events",
  "events": [
    "entry.created",
    "entry.updated",
    "entry.deleted",
    "entry.updated.approved",
    "entry.updated.unapproved",
    "entry.updated.invoiced",
    "entry.updated.uninvoiced"
  ]
}

Response

Status: 201 Created
Location: https://api.nokotime.com/v2/webhooks/123456
{
  "id": 123456,
  "name": "Da Best Noko Webhook",
  "state": "enabled",
  "events": [
    "entry.created",
    "entry.updated",
    "entry.deleted",
    "entry.updated.approved",
    "entry.updated.unapproved",
    "entry.updated.invoiced",
    "entry.updated.uninvoiced"
  ],
  "payload_uri": "http://dabestnokoapp.com/webhooks/entry_events",
  "url": "https://api.nokotime.com/v2/webhooks/123456",
  "add_events_url": "https://api.nokotime.com/v2/webhooks/123456/add_events",
  "remove_events_url": "https://api.nokotime.com/v2/webhooks/123456/remove_events",
  "reroll_secret_url": "https://api.nokotime.com/v2/webhooks/123456/reroll_secret",
  "enable_url": "https://api.nokotime.com/v2/webhooks/123456/enable",
  "disable_url": "https://api.nokotime.com/v2/webhooks/123456/disable",
  "secret": "abcd-1234-secret-value"
}

Storing your webhook’s secret.

You will only receive the webhook’s secret when first creating the webhook, so make sure to store it!

Edit a Webhook

PUT /v2/webhooks/:id

Inputs

name
Optional string
The name of the Webhook
payload_uri
Optional string
The URI to send the payloads to.
{
  "name": "Da Best Noko Webhook",
  "payload_uri": "http://dabestnokoapp.com/webhooks/entry_events"
}

Response

Status: 200 OK
{
  "id": 123456,
  "name": "Da Best Noko Webhook",
  "state": "enabled",
  "events": [
    "entry.created",
    "entry.updated",
    "entry.deleted",
    "entry.updated.approved",
    "entry.updated.unapproved",
    "entry.updated.invoiced",
    "entry.updated.uninvoiced"
  ],
  "payload_uri": "http://dabestnokoapp.com/webhooks/entry_events",
  "url": "https://api.nokotime.com/v2/webhooks/123456",
  "add_events_url": "https://api.nokotime.com/v2/webhooks/123456/add_events",
  "remove_events_url": "https://api.nokotime.com/v2/webhooks/123456/remove_events",
  "reroll_secret_url": "https://api.nokotime.com/v2/webhooks/123456/reroll_secret",
  "enable_url": "https://api.nokotime.com/v2/webhooks/123456/enable",
  "disable_url": "https://api.nokotime.com/v2/webhooks/123456/disable"
}

Add events to a Webhook

PUT /v2/webhooks/:id/add_events

Inputs

events
Required array of strings
The events this webhook should be subscribed to. Any events the webhook is already subscribed to will be ignored and will not affect the response.
You can also specify '*', which is a wildcard for all current and future events.
{
  "events": [
    "entry.created",
    "entry.updated",
    "entry.deleted",
    "entry.updated.approved",
    "entry.updated.unapproved",
    "entry.updated.invoiced",
    "entry.updated.uninvoiced"
  ]
}

Response

Status: 200 OK
{
  "id": 123456,
  "name": "Da Best Noko Webhook",
  "state": "enabled",
  "events": [
    "entry.created",
    "entry.updated",
    "entry.deleted",
    "entry.updated.approved",
    "entry.updated.unapproved",
    "entry.updated.invoiced",
    "entry.updated.uninvoiced"
  ],
  "payload_uri": "http://dabestnokoapp.com/webhooks/entry_events",
  "url": "https://api.nokotime.com/v2/webhooks/123456",
  "add_events_url": "https://api.nokotime.com/v2/webhooks/123456/add_events",
  "remove_events_url": "https://api.nokotime.com/v2/webhooks/123456/remove_events",
  "reroll_secret_url": "https://api.nokotime.com/v2/webhooks/123456/reroll_secret",
  "enable_url": "https://api.nokotime.com/v2/webhooks/123456/enable",
  "disable_url": "https://api.nokotime.com/v2/webhooks/123456/disable"
}

Remove events from a Webhook

PUT /v2/webhooks/:id/remove_events

Inputs

events
Required array of strings
The events this webhook should not be subscribed to. Any events the webhook is not already subscribed to will be ignored and will not affect the response.
{
  "events": [
    "entry.created",
    "entry.updated",
    "entry.deleted",
    "entry.updated.approved",
    "entry.updated.unapproved",
    "entry.updated.invoiced",
    "entry.updated.uninvoiced"
  ]
}

Response

Status: 200 OK
{
  "id": 123456,
  "name": "Da Best Noko Webhook",
  "state": "enabled",
  "events": [
    "entry.created",
    "entry.updated",
    "entry.deleted",
    "entry.updated.approved",
    "entry.updated.unapproved",
    "entry.updated.invoiced",
    "entry.updated.uninvoiced"
  ],
  "payload_uri": "http://dabestnokoapp.com/webhooks/entry_events",
  "url": "https://api.nokotime.com/v2/webhooks/123456",
  "add_events_url": "https://api.nokotime.com/v2/webhooks/123456/add_events",
  "remove_events_url": "https://api.nokotime.com/v2/webhooks/123456/remove_events",
  "reroll_secret_url": "https://api.nokotime.com/v2/webhooks/123456/reroll_secret",
  "enable_url": "https://api.nokotime.com/v2/webhooks/123456/enable",
  "disable_url": "https://api.nokotime.com/v2/webhooks/123456/disable"
}

Re-roll a Webhook’s secret

PUT /v2/webhooks/:id/reroll_secret

Response

Status: 200 OK
{
  "secret": "abcd-1234-secret-value"
}

Disable a Webhook

PUT /v2/webhooks/:id/disable

Response

Status: 204 No Content

Enable a Webhook

PUT /v2/webhooks/:id/enable

Response

Status: 204 No Content

Ping a Webhook

PUT /v2/webhooks/:id/ping

Response

Status: 202 Accepted

Retry a Webhook Payload

PUT /v2/webhooks/:id/retry/:payload_id

Response

Status: 202 Accepted

Delete a Webhook

DELETE /v2/webhooks/:id

Response

Status: 204 No Content