Webhooks

curl -X POST https://api.gogoscreen.com/api/v1/webhooks \
  -H "Authorization: Bearer $GOGOSCREEN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "url": "https://hooks.example.com/gogoscreen",
    "events": ["render.succeeded", "render.failed"],
    "description": "Production receiver"
  }'

HTTP/1.1 201 Created

{
  "secret": "whsec_EXAMPLE_SECRET_SHOWN_ONCE",
  "endpoint": {
    "id": "3f2b0c1a-9d4e-4a61-b8c2-000000000014",
    "url": "https://hooks.example.com/gogoscreen",
    "events": [
      "render.succeeded",
      "render.failed"
    ],
    "description": "Production receiver",
    "status": "active",
    "failureStreak": 0,
    "disabledAt": null,
    "disabledReason": null,
    "lastDeliveryAt": null,
    "createdAt": "2026-09-21T11:19:00.000Z",
    "updatedAt": "2026-09-21T11:19:00.000Z"
  }
}

HTTP/1.1 202 Accepted

{
  "deliveryId": "3f2b0c1a-9d4e-4a61-b8c2-000000000015",
  "eventId": "3f2b0c1a-9d4e-4a61-b8c2-000000000016"
}

HTTP/1.1 200 OK

{
  "data": [
    {
      "id": "3f2b0c1a-9d4e-4a61-b8c2-000000000015",
      "endpointId": "3f2b0c1a-9d4e-4a61-b8c2-000000000014",
      "eventId": "3f2b0c1a-9d4e-4a61-b8c2-000000000016",
      "eventType": "webhook.test",
      "attempt": 1,
      "status": "succeeded",
      "responseStatus": 200,
      "responseMs": 123,
      "lastError": null,
      "nextAttemptAt": null,
      "deliveredAt": "2026-09-21T11:17:00.000Z",
      "createdAt": "2026-09-21T11:17:00.000Z",
      "updatedAt": "2026-09-21T11:17:00.000Z"
    }
  ],
  "nextCursor": null
}

POST /gogoscreen HTTP/1.1
Host: hooks.example.com
Content-Type: application/json
Content-Length: 382
User-Agent: Gogoscreen-Webhooks/1.0
Gogoscreen-Event-Id: 9f9f1c50-2d23-4655-bd53-6c71485d1d55
Gogoscreen-Event-Type: webhook.test
Gogoscreen-Delivery-Id: 01fb5982-302e-40a9-aa0c-223cf480ddf2
Gogoscreen-Delivery-Attempt: 1
Gogoscreen-Signature: t=1790007388,v1=7b1408d576e9cb3c92fe77022cc4afb3af57f14ba81232650b7fbc9a41366d89

{"id":"9f9f1c50-2d23-4655-bd53-6c71485d1d55","data":{"sentAt":"2026-09-21T16:16:28.422Z","message":"This is a test delivery from Gogoscreen. If you can verify its signature, your endpoint is ready.","requestId":"951a5f88-f25a-4e8f-9616-81a302eab2b5","endpointId":"1bb1ee72-8b7b-405e-86fa-eabfcd5f40b9"},"type":"webhook.test","createdAt":"2026-09-21T16:16:28.422Z","apiVersion":"v1"}

{
  "id": "9f9f1c50-2d23-4655-bd53-6c71485d1d55",
  "data": {
    "sentAt": "2026-09-21T16:16:28.422Z",
    "message": "This is a test delivery from Gogoscreen. If you can verify its signature, your endpoint is ready.",
    "requestId": "951a5f88-f25a-4e8f-9616-81a302eab2b5",
    "endpointId": "1bb1ee72-8b7b-405e-86fa-eabfcd5f40b9"
  },
  "type": "webhook.test",
  "createdAt": "2026-09-21T16:16:28.422Z",
  "apiVersion": "v1"
}

const crypto = require("node:crypto");

/**
 * Is this delivery ours, and is it recent?
 *
 * @param {string} secret   the whsec_… value POST /webhooks returned once
 * @param {string} header   the Gogoscreen-Signature value as received
 * @param {string} rawBody  the RAW request body, before any JSON parse
 */
function verifyGogoscreenSignature(secret, header, rawBody, toleranceSeconds = 300) {
  if (typeof header !== "string") return false;

  // t=…,v1=… . First value wins: a header carrying v1 twice is an attempt to
  // have the verifier read one value and a logger read another.
  const parts = {};
  for (const piece of header.split(",")) {
    const eq = piece.indexOf("=");
    if (eq <= 0) continue;
    const k = piece.slice(0, eq).trim();
    if (!(k in parts)) parts[k] = piece.slice(eq + 1).trim();
  }

  const t = Number(parts.t);
  if (!Number.isFinite(t) || !parts.v1) return false;

  // The replay window. The timestamp is INSIDE the MAC, so a recorded delivery
  // cannot be given a fresh t without forging the signature.
  if (Math.abs(Math.floor(Date.now() / 1000) - t) > toleranceSeconds) return false;

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${t}.${rawBody}`, "utf8")
    .digest("hex");

  // Length first: timingSafeEqual THROWS on a length mismatch.
  const a = Buffer.from(expected, "utf8");
  const b = Buffer.from(parts.v1, "utf8");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

module.exports = { verifyGogoscreenSignature };

HTTP/1.1 400 Bad Request

{
  "error": {
    "code": "webhook_url_blocked",
    "message": "That webhook URL resolves to an address this API will not post to. Point it at a public address.",
    "details": { "reason": "IPv6 loopback", "host": "example.com" },
    "requestId": "4eb7b9f7-85c7-4f68-be3f-0a6b85265ad7"
  }
}

HTTP/1.1 400 Bad Request

{
  "error": {
    "code": "webhook_url_invalid",
    "message": "That webhook URL is not one this API will post to. Use an https URL with no username, password or fragment.",
    "details": { "reason": "bare_host" },
    "requestId": "dd82496b-e3e5-4521-a347-e74d665d980b"
  }
}