Webhooks

Ein Crowd-Job-Webhook ist ein ausgehender HTTP-Callback, den Sie konfigurieren, um einen Ihrer eigenen Endpunkte zu benachrichtigen, sobald bei einem Job etwas passiert — eine Statusänderung oder eine eingegangene, akzeptierte oder abgelehnte Worker-Antwort. Ein einzelner Job kann beliebig viele unabhängige Webhooks haben, jeder mit einer eigenen Teilmenge abonnierter Ereignistypen, sodass Sie unterschiedliche Ereignisse an unterschiedliche Systeme weiterleiten können (zum Beispiel Lebenszyklus-Ereignisse an eine Slack-Integration und vollständige Antwort-Payloads an Ihre eigene Datenpipeline).

Webhooks werden pro Job konfiguriert, entweder bei der Erstellung oder nachträglich, und können sowohl über die API als auch über den Tab Webhooks des Jobs in der Plattform-UI verwaltet werden.

EreignistypenCopy Anchor Link

Einen Webhook erstellenCopy Anchor Link

Webhook-URLs müssen https:// verwenden und öffentlich aus dem Internet erreichbar sein — Crowdee lehnt URLs ab, die zu einer privaten, Loopback- oder Link-Local-Adresse auflösen (zum Beispiel 127.0.0.1, 10.0.0.0/8 oder die verbreitete Cloud-Metadaten-Adresse 169.254.169.254) — als Sicherheitsmaßnahme.

curl -X POST https://api.crowdee.ai/v2/crowd-jobs/{jobId}/webhooks \
  -H "X-API-Key: crw_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/crowdee",
    "description": "Slack notifier",
    "eventTypes": ["job.finished", "job.archived", "answer.accepted", "answer.rejected"]
  }'

Die 201 Created-Antwort enthält das Webhook-Objekt und dessen Signatur-Secret im Klartext:

{
  "id": "whk_a1b2c3d4e5f6g7h8i9j0k1l2",
  "jobId": "job_abc123def456ghi789jkl01",
  "url": "https://example.com/webhooks/crowdee",
  "description": "Slack notifier",
  "eventTypes": ["job.finished", "job.archived", "answer.accepted", "answer.rejected"],
  "status": "active",
  "secret": "whsec_9f8a7b6c5d4e3f2a1b0c9d8e7f6a5b4c"
}

Sie können auch bereits bei der Job-Erstellung einen oder mehrere Webhooks anlegen, indem Sie ein webhooks-Array in die Payload zur Job-Erstellung aufnehmen:

{
  "name": "Q3 Image Authenticity Review",
  "title": "...",
  "description": "...",
  "surveyTemplateVersionId": "tmplv_abc123def456ghi789jkl01",
  "webhooks": [
    { "url": "https://example.com/webhooks/crowdee", "eventTypes": ["job.finished", "answer.accepted"] }
  ]
}

Die Antwort auf die Job-Erstellung enthält dann zusätzlich zu den Feldern des erstellten Jobs ein webhooks-Array, wobei jeder Eintrag sein eigenes einmaliges secret trägt.

Payload und ZustellungCopy Anchor Link

Jede Zustellung ist ein HTTP-POST mit einem Content-Type: application/json-Body. Ereignistyp und Zustellungs-Identität werden in Headern übertragen, nicht im Body — der Body ist einfach das reine Payload-Objekt für dieses Ereignis:

Job-Lebenszyklus-Ereignisse (job.created, job.paused, job.resumed, job.archived) teilen sich diesen Aufbau:

{
  "jobId": "job_abc123def456ghi789jkl01",
  "title": "Assess whether this image has been digitally manipulated",
  "status": "archived",
  "category": "survey",
  "projectId": "proj_xyz987stu654rqp321onm09"
}

job.finished, job.no_tasks und job.expired enthalten zusätzlich den Status, aus dem der Job übergegangen ist:

{
  "jobId": "job_abc123def456ghi789jkl01",
  "title": "...",
  "status": "finished",
  "category": "survey",
  "projectId": "proj_xyz987stu654rqp321onm09",
  "previousStatus": "no_tasks"
}

job.extended enthält zusätzlich die Höhe der Erweiterung:

{
  "jobId": "job_abc123def456ghi789jkl01",
  "title": "...",
  "status": "assignable",
  "category": "survey",
  "projectId": "proj_xyz987stu654rqp321onm09",
  "additionalRepetitions": 5,
  "newMaxRepetitionsPerVariant": 15
}

answer.received (schlank):

{
  "answerId": "ans_abc123",
  "jobId": "job_abc123def456ghi789jkl01",
  "taskId": "tsk_xyz987",
  "workerId": "usr_ghi789",
  "guestWorkerId": null,
  "submittedAt": "2025-09-14T10:23:41Z",
  "variantIndex": 7
}

answer.received.full — identisch im Aufbau zu einer Zeile aus dem JSON-Antwortexport, einschließlich des Survey-answers-Objekts, der Worker-Metadaten und des Input-Data-Snapshots. feedback ist hier immer null, da etwaiges Worker-Feedback erst nach diesem Zeitpunkt eingereicht wird.

answer.accepted / answer.rejected:

{
  "answerId": "ans_abc123",
  "jobId": "job_abc123def456ghi789jkl01",
  "taskId": "tsk_xyz987",
  "workerId": "usr_ghi789",
  "guestWorkerId": null,
  "reviewedById": "usr_reviewer01",
  "rejectionReason": "Response does not address the required criteria.",
  "rejectionCategory": "failed_instructions"
}

(rejectionReason/rejectionCategory sind bei answer.accepted null; stattdessen wird acceptanceNote mitgeliefert, sofern eine angegeben wurde.)

Signatur verifizierenCopy Anchor Link

X-Crowdee-Signature folgt demselben Schema, das auch Stripe verwendet: t=<unix_timestamp>,v1=<hex_hmac_sha256>. Die Signatur ist ein HMAC-SHA256 über den String {timestamp}.{roher Request-Body}, mit dem Secret Ihres Webhooks als Schlüssel.

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

function isValidCrowdeeSignature(rawBody, signatureHeader, secret) {
  const parts = Object.fromEntries(
    signatureHeader.split(",").map((part) => part.split("=")),
  );
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(parts.v1, "hex"),
    Buffer.from(expected, "hex"),
  );
}

Wiederholungsversuche, Zustellungsprotokoll und erneute ZustellungCopy Anchor Link

Eine Zustellung, die keine 2xx-Antwort erhält, wird automatisch mit exponentiellem Backoff wiederholt, bis zu 8 Versuche über einen Zeitraum von etwa 2 Stunden verteilt — lang genug, um einen kurzzeitigen Ausfall auf Ihrer Seite zu überstehen, ohne dass Sie eingreifen müssen. Weiterleitungen (3xx) werden als Fehlschlag behandelt statt ihnen zu folgen.

Aktuelle Zustellungen eines Webhooks ansehen:

curl "https://api.crowdee.ai/v2/crowd-jobs/{jobId}/webhooks/{webhookId}/deliveries?limit=50" \
  -H "X-API-Key: crw_YOUR_API_KEY"

{
  "total": 12,
  "items": [
    {
      "id": "whd_1a2b3c4d5e6f7g8h9i0j1k2l",
      "event": "answer.rejected",
      "status": "succeeded",
      "attempt": 1,
      "responseStatusCode": 200,
      "durationMs": 184,
      "createdAt": "2025-09-14T10:23:42Z",
      "deliveredAt": "2025-09-14T10:23:42Z"
    }
  ]
}

status ist entweder pending, succeeded, failed (wird wiederholt) oder exhausted (alle Versuche sind fehlgeschlagen). Eine erschöpfte (oder anderweitig fehlgeschlagene) Zustellung manuell erneut anstoßen:

curl -X POST https://api.crowdee.ai/v2/crowd-jobs/{jobId}/webhooks/{webhookId}/deliveries/{deliveryId}/redeliver \
  -H "X-API-Key: crw_YOUR_API_KEY"

Die erneute Zustellung erzeugt eine neue Zustellung mit eigener ID und eigenem Budget von 8 Versuchen — die ID und der Versuchszähler der ursprünglichen Zustellung werden nicht wiederverwendet.

Automatische DeaktivierungCopy Anchor Link

Sammelt ein Webhook 10 aufeinanderfolgende vollständig erschöpfte Zustellungen an — jeder Wiederholungsversuch aller zehn Zustellungen ist fehlgeschlagen, ohne dass dazwischen eine erfolgreiche Zustellung lag —, setzt Crowdee ihn automatisch auf status: "disabled" und benachrichtigt die Watcher und Reviewer des Jobs per E-Mail. Ein deaktivierter Webhook erhält keine neuen Zustellungen mehr, bis Sie ihn wieder aktivieren.

Mit einer Update-Anfrage wieder aktivieren:

curl -X PUT https://api.crowdee.ai/v2/crowd-jobs/{jobId}/webhooks/{webhookId} \
  -H "X-API-Key: crw_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "active" }'

Die Reaktivierung setzt den Zähler aufeinanderfolgender Fehlschläge auf null zurück — es braucht also wieder zehn in Folge, bevor der Webhook erneut automatisch deaktiviert würde.

Webhooks verwaltenCopy Anchor Link

Webhooks eines Jobs auflisten:

GET https://api.crowdee.ai/v2/crowd-jobs/{jobId}/webhooks
X-API-Key: crw_YOUR_API_KEY

Einen Webhook aktualisieren — URL, Beschreibung, abonnierte Ereignisse oder Status ändern:

curl -X PUT https://api.crowdee.ai/v2/crowd-jobs/{jobId}/webhooks/{webhookId} \
  -H "X-API-Key: crw_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "eventTypes": ["job.finished", "job.archived"] }'

Signatur-Secret rotieren — invalidiert das alte Secret sofort und liefert ein neues zurück (einmalig angezeigt, genau wie bei der Erstellung):

curl -X POST https://api.crowdee.ai/v2/crowd-jobs/{jobId}/webhooks/{webhookId}/rotate-secret \
  -H "X-API-Key: crw_YOUR_API_KEY"

Ein Testereignis senden — liefert sofort und synchron eine künstliche webhook.test-Payload aus (wird nicht wiederholt und nicht im Zustellungsprotokoll erfasst), sodass Sie beim Einrichten Ihres Endpunkts ein sofortiges Erfolgs-/Fehlschlagsergebnis erhalten:

curl -X POST https://api.crowdee.ai/v2/crowd-jobs/{jobId}/webhooks/{webhookId}/test \
  -H "X-API-Key: crw_YOUR_API_KEY"

{ "ok": true, "statusCode": 200, "errorMessage": null, "durationMs": 142 }

Einen Webhook löschen — er erhält danach keine weiteren Zustellungen mehr. Dies kann nicht rückgängig gemacht werden; legen Sie ihn bei Bedarf neu an (und aktualisieren Sie das Secret auf der Empfängerseite):

curl -X DELETE https://api.crowdee.ai/v2/crowd-jobs/{jobId}/webhooks/{webhookId} \
  -H "X-API-Key: crw_YOUR_API_KEY"