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.
- Open the job’s page.
- Under Webhooks, click Add endpoint.
- Enter a Name, such as
Payment received. - Choose the verification method that matches the sender, then enter the credentials it needs. See Webhook Verification for each method.
- Click Add Endpoint.
- 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
410for 30 days, then404. 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.