Webhooks#

A webhook starts a job when another service sends an event. This guide shows how to add an endpoint, read the delivery in your script, and handle the common lifecycle.

GearTrain supports several verification methods. Standard Webhooks is the default. See Webhook Verification to choose a method and configure the sender.

When to Use a Webhook#

Use a webhook when another service already knows when the work should happen. A payment, a form submission, a completed build, or an alert can start the job immediately instead of waiting for a schedule.

Use a schedule when nothing else will tell you when to run. Use both when events should start most runs and a scheduled run should also catch missed events or correct state.

For a comparison of all trigger types, see Choosing a Trigger.

Add an Endpoint#

Each endpoint has its own URL and credentials. A job can have several endpoints, so different senders can start the same job with separate secrets.

  1. Open the job’s page.
  2. Under Webhooks, click Add endpoint.
  3. Enter a Name, such as Payment received.
  4. Choose the verification method that matches the sender, then enter the credentials it needs. See Webhook Verification for each method.
  5. Click Add Endpoint.
  6. Copy the endpoint URL and give it to the sender.

The secret is stored encrypted and is never shown again. If you lose it, delete the endpoint and add a new one with a new secret. The verification method and secret cannot be changed after creation. A job can have up to 10 active endpoints.

Use the Enabled checkbox on an endpoint to stop deliveries without deleting the endpoint. Use Delete to remove the endpoint. Its URL returns 410 for 30 days.

Read the Delivery in a Script#

The context module reports what started the run and the delivery data:

import context from "context";

if (context.delivery) {
    const payload = context.delivery.json();

    console.log(context.trigger);
    console.log(context.delivery.id);
    console.log(context.delivery.timestamp);
    console.log(context.delivery.verified);
    console.log(payload);
}

context.trigger is "schedule", "manual", or "webhook". context.delivery is null when the run has no payload.

delivery.timestamp is null when the verification method has no signed timestamp. delivery.verified is false when the endpoint uses the unverified URL mode or when the payload comes from a manual test run. delivery.json() parses JSON bodies; for text or form bodies, read delivery.body.

See the context module for the full contract.

Test With a Manual Payload#

The workbench Run now panel has an optional Test with a payload editor. Paste the body a sender would deliver, then start the run.

A manual run with a payload keeps context.trigger as "manual" and exposes the payload as context.delivery. This lets you exercise payload-handling code without sending a real webhook. Manual payloads are not sender-verified, so context.delivery.verified is false.

The payload is limited to 256 KB and is not retained after the run.

Responses and Retries#

Rejected deliveries use the same JSON error shape as the REST API:

{
  "ok": false,
  "error": {
    "code": "invalid_payload",
    "message": "The request body is not valid for this webhook source."
  },
  "requestId": "req_..."
}
Status Code Meaning What the sender should do
202 The delivery was accepted and a run will start. Stop.
400 invalid_payload The body is not valid UTF-8, or not valid JSON when the method requires JSON. Send a UTF-8 body in the format the method accepts.
401 invalid_signature The signature, timestamp, or required headers are invalid for the selected method. Check the secret and the signing code.
404 unknown_endpoint No endpoint has that URL. Check the URL.
405 method_not_allowed The request did not use POST. Send a POST request.
410 endpoint_gone The endpoint or its job was deleted. Remove the URL.
413 payload_too_large The body is larger than 256 KB. Send a smaller body.
415 unsupported_media_type The content type or encoding is not accepted by the selected method. Send a supported content type without compression.
429 rate_limited or quota_exceeded The rate limit or the monthly run limit was reached. Retry later, using Retry-After when provided.
500 internal_error Unexpected server error. Retry later.
503 job_paused, endpoint_disabled, or queue_unavailable The job is paused, the endpoint is disabled, or the service is unavailable. Retry later, using Retry-After when provided.

An accepted delivery returns 202 with:

{
  "ok": true,
  "requestId": "req_..."
}

The hook response has no data object. A 202 means the delivery was accepted. It does not mean the script has finished, and the sender cannot read the run result.

If the same delivery ID is sent again within 24 hours, GearTrain returns 202 without starting another run when the method provides a delivery ID. Deliveries may still arrive out of order, and a sender may send the same event more than once. Use context.delivery.id as an idempotency key when the script must avoid duplicate work.

Pause, Disable, and Delete#

  • Pause the job: scheduled and webhook runs stop. Deliveries return 503. Manual runs still work.
  • Disable an endpoint: that endpoint returns 503. Other endpoints and the schedule keep working.
  • Delete an endpoint: the URL returns 410 for 30 days, then 404. The secret is destroyed.
  • Delete the job: all of its endpoints return 410.

Limits#

Limit Value
Body size 256 KB
Endpoints per job 10 active endpoints
Duplicate window 24 hours when the method provides a delivery ID
Rate limit Your plan’s API requests per minute, applied per endpoint and per source IP

Webhook runs count toward your monthly run limit and the concurrent run limit.

Test a Delivery#

Send a delivery from your own machine with the example sender for your verification method. See Webhook Verification. Open the run under Runs to see the console output. The run details show Webhook as the trigger and the endpoint name.

Reference#