Async jobs and webhooks

​

How does a background job work?

1. A POST or PATCH request starts the job and returns right away with an ID.
2. The job runs in the background.
3. You find out it finished in one of two ways:
   • Polling: your server checks the job’s status every few seconds. See Poll for results.
   • Webhooks: CrazyGoldFish calls your server as soon as the job finishes. See Receive webhooks.
4. You fetch the result with a GET request.

​

Job status values

​

Poll for results

• Poll every 5 seconds. Faster polling doesn’t make jobs finish sooner.
• Expect a short 404 at the start. Right after you start a Lesson Plan or Worksheet job, its GET endpoint returns 404 with a step not found message until a worker picks the job up. Keep polling.
• A failed job usually returns 400, with "status": "Failed" and a msg explaining why. Action Plans, ClassTrack, and Get lesson plan content return 200 with "status": "Failed" instead, so check status on every 200 too.
• Set a timeout. Some failures leave a job In Progress. If a job hasn’t completed after 10 minutes, stop polling, start a new job, and contact CrazyGoldFish with the job ID.

​

Receive webhooks

​

Register a webhook

curl https://api.crazygoldfish.com/webhooks/v1/webhook-api-templates/ \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

[
  {
    "id": "2820c61f-64f8-4a24-9276-6ef855864772",
    "name": "worksheet_generation",
    "display_name": "Worksheet Generation",
    "description": null
  }
]

curl -X POST https://api.crazygoldfish.com/webhooks/v1/webhook/ \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "api_template": "2820c61f-64f8-4a24-9276-6ef855864772",
    "endpoint_url": "https://example.com/webhooks/crazygoldfish",
    "secret_hash": "a-long-random-string-you-generate"
  }'

• endpoint_url must start with https://. A successful registration returns 201.
• Each API user can register one webhook per event. A second one returns 400 Webhook already exists.
• To change the URL, send PATCH /webhooks/v1/webhook/{id}/. It requires endpoint_url and replaces the stored one, and if you leave out secret_hash, the saved secret is removed. Send both fields every time.
• There is no endpoint to delete a webhook. Contact CrazyGoldFish to disable one.
• Template IDs differ between environments, so read them from the templates call rather than hardcoding them.
• If registration succeeded and your jobs complete but nothing ever arrives, your API user may not be fully set up for delivery. Contact CrazyGoldFish.

​

Events

​

Payloads

{
  "id": "152764ca-1685-427c-aba7-4b92dcc0d60f",
  "name": "worksheet_generation",
  "display_name": "Worksheet Generation",
  "secret_hash": "a-long-random-string-you-generate",
  "status": "Completed"
}

{
  "status": "Completed",
  "exam_id": "d19e6868-98dd-4274-a2a5-4a616dd93ea7",
  "ans_sheet_id": "8a2f4c1e-5b3d-4e6f-9a7b-0c1d2e3f4a5b",
  "name": "exam_evaluation_student_answer_sheet_evaluation",
  "display_name": "Student Answer Sheet Evaluation",
  "secret_hash": "a-long-random-string-you-generate"
}

{
  "status": "Completed",
  "assignment_id": "3c9e1f2a-7b4d-4a8e-9f1c-2d5e6a7b8c9d",
  "ans_sheet_id": "6e1d2c3b-4a5f-4e6d-8c7b-9a0f1e2d3c4b",
  "webhook_name": "assignment_evaluation_student_answer_sheet_evaluation",
  "secret_hash": "a-long-random-string-you-generate"
}

​

Handle deliveries

• Verify the sender. Compare secret_hash with the secret you registered, and reject the request if they don’t match.
• Respond within 5 seconds with a 2xx status. Do slow work after you respond.
• Keep polling as a fallback. Most events are sent once with no retry. exam_evaluation_student_answer_sheet_evaluation is retried once after 5 seconds if your endpoint doesn’t return 200 or 201.
• Handle duplicates. Because of retries, the same event can arrive twice.

import hmac
import os

from flask import Flask, abort, request

app = Flask(__name__)
WEBHOOK_SECRET = os.environ["CRAZYGOLDFISH_WEBHOOK_SECRET"]


@app.post("/webhooks/crazygoldfish")
def crazygoldfish_webhook():
    event = request.get_json()
    if not hmac.compare_digest(event.get("secret_hash") or "", WEBHOOK_SECRET):
        abort(401)
    event_name = event.get("name") or event.get("webhook_name")
    queue_job(event_name, event)  # Fetch the result in a background worker
    return "", 200

import crypto from "node:crypto";
import express from "express";

const app = express();
const WEBHOOK_SECRET = process.env.CRAZYGOLDFISH_WEBHOOK_SECRET;

function isValidSecret(received = "") {
  const a = Buffer.from(received);
  const b = Buffer.from(WEBHOOK_SECRET);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

app.post("/webhooks/crazygoldfish", express.json(), (req, res) => {
  if (!isValidSecret(req.body.secret_hash ?? "")) return res.sendStatus(401);
  const eventName = req.body.name ?? req.body.webhook_name;
  queueJob(eventName, req.body); // Fetch the result in a background worker
  res.sendStatus(200);
});