Webhooks
A webhook sends your server a small signed message when a defect changes, so you do not have to keep asking. Each event says what happened and to which record. Read the record for the details.
Subscribing
A company admin adds a webhook in Settings > Public API, in the Webhooks section, with Add webhook. The admin gives a name, an HTTPS address and the events to send. The address must use port 443 or 8443, and addresses on private or internal networks are refused.
The signing secret starts whsec_ and is shown once, straight after the webhook is added. A company can have up to 10 webhooks.
Send test event sends a webhook.test event to the address straight away, so you can check your receiver before any defect changes.
Events
There are seven event types. Three are below and the rest follow.
Every defect event also says in source where it came from: app, api or sync.
Updates
Note event
note.added is sent when a note is added from the app, by a subcontractor or by software.
Payload
The body is JSON with five keys: id, type, occurred_at, api_version and data. The id is the event id and equals the webhook-id header. Times are ISO 8601 in UTC, ending in Z.
Every defect event carries the same 13 keys in data: resource_type (always defect), defect_id, project_id, status, previous_status, status_group, changed_fields, modified_at, actor, source, note_id, audience and deleted_at. Every key is always present and is null where it does not apply. For example previous_status is filled only on defect.status_changed and defect.closed, changed_fields only on defect.updated, note_id and audience only on a note event, and deleted_at only on defect.deleted.
The payload is thin on purpose. It never holds note text, names, emails, photo links, numbers or descriptions. Treat an event as a hint and read the defect with GET /v1/defects/{defectId} for its current state. A deleted defect is no longer returned, so remove your copy by defect_id.
Field names
changed_fields is sorted and uses the public names: closed_at, custom_type, description, due_date, external_ids, issued_to, location_id, notes, number, photos, priority, project_id, raised_by and type. A webhook.test event holds subscription_id and message in data instead.
Delivery
Each event is sent with POST and these headers:
- →
content-type:application/json - →
webhook-id: the event id, the same on every attempt - →
webhook-timestamp: whole seconds since the Unix epoch, new on every attempt - →
webhook-signature: onev1,entry for each live secret - →
user-agent:IssuesID-Webhooks/1 - →
x-issuesid-event: the event type, such asdefect.created
Answer with any 2xx within 15 seconds (5 to connect, 10 for the headers and body). Anything else is a failed attempt, including a redirect, which is never followed. The response body is never stored.
Delivery is at least once and not ordered. The same event can arrive twice, and a later event can arrive before an earlier one. Dedupe on webhook-id, and decide what is newest from modified_at or by reading the defect, never from arrival order. A retry carries the same body and the same webhook-id, with a new webhook-timestamp and signature.
Retries
A failed delivery gets eight attempts in all over about 27 hours. The gaps after the first seven attempts are about 5 seconds, 5 minutes, 30 minutes, 2 hours, 5 hours, 10 hours and 10 hours, each up to 10 percent either way. A Retry-After on a 429 or 503 is honoured when it asks for a later time that is still inside that window. At most 4 deliveries to one webhook are in flight at once, so a burst of events is paced, not dropped.
A webhook with no success for 24 hours and at least one failure in that time is paused at its next failed attempt. The 24 hours count from the later of the last success and the last resume. A 410 Gone pauses it at once. Deliveries still waiting are cancelled, and the admin who added the webhook is emailed, or the company admins if that admin has left.
While a webhook is paused nothing is sent. Resume starts events again but does not replay what happened during the pause, so run a reconciliation walk with updated_since as the paging article describes. View deliveries shows the last 30 days with every attempt and can resend a delivery. A resend sends the same body once, with no further retries.
Signatures
Each delivery is signed with HMAC-SHA256, as Standard Webhooks version 1 describes. The signed text is the webhook-id, the webhook-timestamp and the raw body, joined with full stops. The key is the base64 decoding of the secret after whsec_. The signature is v1, followed by the base64 of the result. The webhook-signature header holds one entry for each live secret, separated by spaces, and a match with any of them is enough.
Check the raw bytes you received, never re-serialised JSON. Compare in constant time, and reject a timestamp more than 5 minutes (300 seconds) from your clock.
Rotation
A company admin rotates a secret with Rotate secret and chooses how long the old one keeps working: 24 hours, 7 days or 30 days. The new secret is shown once. During the overlap every delivery carries two v1, entries, one for each secret, so a receiver should accept either, and the Node and Python code below does. End overlap now drops the old secret straight away, and after that deliveries carry one signature.
A webhook has at most two live secrets, so a second rotation has to wait until the overlap ends.
Source address
There is no fixed source IP for webhooks, so do not allow-list by IP. Check the signature instead, and reject a timestamp more than 5 minutes off. Webhook addresses must use HTTPS.
curl
This checks one delivery you have saved to a file, using openssl:
# SECRET="whsec_..." ID=<webhook-id> TS=<webhook-timestamp>
# BODY_FILE=<the body, saved exactly as received>
KEY_HEX=$(printf '%s' "${SECRET#whsec_}" | base64 -d | xxd -p -c 256)
{ printf '%s.%s.' "$ID" "$TS"; cat "$BODY_FILE"; } \
| openssl dgst -sha256 -mac HMAC -macopt hexkey:"$KEY_HEX" -binary \
| base64
# Compare the output with the part after "v1," in any entry of the
# webhook-signature header.Node
In Node 20 or later, verifyWebhook takes the secrets you hold, the request headers with lower case names, and the raw body:
import { createHmac, timingSafeEqual } from 'node:crypto';
const TOLERANCE_SECONDS = 300;
// secrets: the whsec_ values you hold (two while a secret is being
// rotated).
// rawBody: the request body exactly as received, a string or Buffer,
// never re-serialised JSON.
export function verifyWebhook(secrets, headers, rawBody) {
const id = headers['webhook-id'];
const timestamp = headers['webhook-timestamp'];
const signatures = headers['webhook-signature'];
if (!id || !timestamp || !signatures) return false;
const now = Math.floor(Date.now() / 1000);
const age = Math.abs(now - Number(timestamp));
if (!Number.isFinite(age) || age > TOLERANCE_SECONDS) return false;
// Sign the bytes as received: a Buffer is never decoded and re-encoded.
const signed = Buffer.concat([
Buffer.from(`${id}.${timestamp}.`),
Buffer.isBuffer(rawBody) ? rawBody : Buffer.from(rawBody),
]);
const received = signatures
.split(' ')
.filter((entry) => entry.startsWith('v1,'))
.map((entry) => Buffer.from(entry.slice(3), 'base64'));
return secrets.some((secret) => {
const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64');
const expected = createHmac('sha256', key).update(signed).digest();
return received.some((sig) => {
if (sig.length !== expected.length) return false;
return timingSafeEqual(sig, expected);
});
});
}Python
In Python 3.9 or later, with the standard library only:
import base64
import hashlib
import hmac
import time
TOLERANCE_SECONDS = 300
def verify_webhook(secrets, headers, raw_body):
"""secrets: the whsec_ values you hold (two while a secret is
being rotated).
raw_body: the request body exactly as received (bytes)."""
webhook_id = headers.get("webhook-id")
timestamp = headers.get("webhook-timestamp")
signatures = headers.get("webhook-signature")
if not webhook_id or not timestamp or not signatures:
return False
try:
age = abs(int(time.time()) - int(timestamp))
except ValueError:
return False
if age > TOLERANCE_SECONDS:
return False
signed = f"{webhook_id}.{timestamp}.".encode() + raw_body
received = [
entry[3:] for entry in signatures.split(" ")
if entry.startswith("v1,")
]
for secret in secrets:
key = base64.b64decode(secret.removeprefix("whsec_"))
digest = hmac.new(key, signed, hashlib.sha256).digest()
expected = base64.b64encode(digest)
# Compare bytes: compare_digest raises on non-ASCII str, and
# the header is whatever the sender put there.
if any(hmac.compare_digest(sig.encode(), expected) for sig in received):
return True
return FalseAvoiding loops
Every defect event carries actor and source in data. actor.type is user for a person in the app, api for an API key or system for the platform. For api, actor.id is the id of the API user behind the key.
To ignore edits your own software made, skip an event when actor.type is api and actor.id equals the actor.id that GET /v1/me returns for your key. A write that alters nothing sends no event, so repeating a write does not echo back.
An edit made without a login, such as a trade answering from an emailed link, has actor.type of system and an actor.id of null.
The event shapes are listed under Models in the API reference.