Register a webhook

POST

webhooks

webhook

curl --request POST \
  --url https://api.crazygoldfish.com/webhooks/v1/webhook/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "api_template": "ff4be808-b444-49b8-b7f3-9b78258e03b7",
  "endpoint_url": "https://example.com/webhooks/crazygoldfish"
}
'

import requests

url = "https://api.crazygoldfish.com/webhooks/v1/webhook/"

payload = {
    "api_template": "ff4be808-b444-49b8-b7f3-9b78258e03b7",
    "endpoint_url": "https://example.com/webhooks/crazygoldfish"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    api_template: 'ff4be808-b444-49b8-b7f3-9b78258e03b7',
    endpoint_url: 'https://example.com/webhooks/crazygoldfish'
  })
};

fetch('https://api.crazygoldfish.com/webhooks/v1/webhook/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "id": "c5a71f30-6b82-4d19-9e4a-8f0d3b6c2157",
  "api_template": {
    "id": "ff4be808-b444-49b8-b7f3-9b78258e03b7",
    "name": "exam_evaluation_student_answer_sheet_evaluation",
    "display_name": "Exam Evaluation Answer Sheet Evaluation",
    "description": ""
  },
  "endpoint_url": "https://example.com/webhooks/crazygoldfish"
}

Register one webhook per event you care about. For the full event list, delivery payloads, and receiver code, see Async jobs and webhooks.

Rules

api_template is a template id from List webhook event templates. It cannot be changed later.
endpoint_url must be a valid URL starting with lowercase https://. Plain http:// is rejected with Enter a valid URL.
Each API user gets one webhook per event. A second one returns 400 with Webhook already exists.
Keep the trailing slash on the path. Without it the API redirects, and most HTTP clients drop the request body when they follow a redirect.
A successful registration returns 201, not 200.
New webhooks are enabled straight away.

Register with the same API user that starts the jobs. A webhook only fires for jobs started by the API user that created it. If one service starts jobs and another registers the webhook, nothing is ever delivered.

secret_hash is optional, but send one. CrazyGoldFish stores it encrypted and puts it back in the body of every delivery, so your receiver can compare it and reject anything that does not match. Keep your own copy: no endpoint ever reads the secret back to you.

Because there is no endpoint to delete a webhook, you cannot re-register an event to fix a typo. Change the existing one with Update a webhook instead.

Troubleshooting

If registration returned 201, your jobs finish, and your endpoint is reachable, but no delivery ever arrives, the account may not be set up for webhook delivery. Nothing is returned to you in that case, and no error appears on the job. Contact CrazyGoldFish and we will check the setup. In the meantime, poll for results.

Next step

Update a webhook

Change the address or the secret later, without losing the registration.

Authorizations

Authorization

string

header

required

Access token from Get an access token.

Body

application/json

api_template

string<uuid>

required

Template id of the event, read from List webhook event templates. Look the event up by name each time rather than hardcoding an id.

Example:

"ff4be808-b444-49b8-b7f3-9b78258e03b7"

endpoint_url

string<uri>

required

Your receiver's address. It must be a valid URL starting with lowercase https://. Plain http:// is rejected.

Example:

"https://example.com/webhooks/crazygoldfish"

secret_hash

string

A random string you generate. CrazyGoldFish stores it encrypted and sends it back in the body of every delivery, so your receiver can compare it and reject anything else. Optional, but without it deliveries carry "secret_hash": null and you cannot tell a real delivery from a forged one.

Example:

"a-long-random-string-you-generate"

Response

The webhook is registered and enabled. The secret is stored encrypted and is not echoed back here.

A registered webhook. The secret is never returned by these endpoints.

string<uuid>

Unique ID of the webhook. Use it in Get a webhook and Update a webhook.

Example:

"c5a71f30-6b82-4d19-9e4a-8f0d3b6c2157"

api_template

object

The event this webhook listens for, expanded. It cannot be changed after registration.

Show child attributes

endpoint_url

string<uri>

The HTTPS address CrazyGoldFish posts the event to.

Example:

"https://example.com/webhooks/crazygoldfish"

curl --request POST \
  --url https://api.crazygoldfish.com/webhooks/v1/webhook/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "api_template": "ff4be808-b444-49b8-b7f3-9b78258e03b7",
  "endpoint_url": "https://example.com/webhooks/crazygoldfish"
}
'

import requests

url = "https://api.crazygoldfish.com/webhooks/v1/webhook/"

payload = {
    "api_template": "ff4be808-b444-49b8-b7f3-9b78258e03b7",
    "endpoint_url": "https://example.com/webhooks/crazygoldfish"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    api_template: 'ff4be808-b444-49b8-b7f3-9b78258e03b7',
    endpoint_url: 'https://example.com/webhooks/crazygoldfish'
  })
};

fetch('https://api.crazygoldfish.com/webhooks/v1/webhook/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "id": "c5a71f30-6b82-4d19-9e4a-8f0d3b6c2157",
  "api_template": {
    "id": "ff4be808-b444-49b8-b7f3-9b78258e03b7",
    "name": "exam_evaluation_student_answer_sheet_evaluation",
    "display_name": "Exam Evaluation Answer Sheet Evaluation",
    "description": ""
  },
  "endpoint_url": "https://example.com/webhooks/crazygoldfish"
}

Get started

Guides

Exam Evaluation

Assignment Evaluation

Rubrics

Action Plans

Lesson Plan Builder

Worksheet Builder

ClassTrack

Metadata

Webhooks

Rules

Troubleshooting

Next step

Update a webhook

Authorizations

Body

Response

​Rules

​Troubleshooting

​Next step

Update a webhook

Authorizations

Body

Response

Rules

Troubleshooting

Next step