/ /
A webhook is an automated message that one system sends to another the moment something happens. The sending system posts the details of the event to a URL, and whatever listens at that URL acts on them. It is how DevRev announces a ticket creation, Stripe announces a completed payment, how GitHub announces a merged pull request, and how PagerDuty announces a new incident.
A webhook trigger gives a DevRev workflow such a URL. When an external system sends an event to it, the workflow runs with that event's data. The sending system needs no DevRev account or token, only the URL. This makes webhooks the entry point for anything that happens outside DevRev: a merged pull request, a completed payment, an incident, a web form submission, or an alert from your own service.
Webhooks are native to the Workflow Builder. Receiving and parsing an external event no longer requires a snap-in or an intermediary service to bridge the event into DevRev.
A webhook is a reusable object, not a property of a single workflow. One webhook URL registered in an external system can start any number of workflows, each with its own filter conditions. This matters because external systems cap how many webhooks you can register: GitHub allows roughly 20 per repository and Jira roughly 50 per plan. Registering one URL in GitHub and fanning it out to ten DevRev workflows stays well inside those caps, where ten separate URLs would not.
Webhook selection
When you add a Webhook trigger to a workflow, the first decision is whether to create a webhook or reuse one that already exists.
Create a new webhook
DevRev generates a URL that you register in the external system. Use this path the first time you connect a system, or when you want a URL dedicated to one source.
Use an existing webhook
You select a previously created webhook by name. The URL is already live in the external system and events are already arriving, so you skip both the registration step and the wait for test traffic. A webhook becomes available for reuse only after its creator has added it to a workflow and completed the listening step, and the creator has to pass it to you — you cannot discover another person's webhooks yourself.
💡 Tip: Name webhooks after the system and scope they cover, for example
GitHub — platform reporather thanwebhook 1. The name is how teammates identify the webhook when they reuse it in other workflows.
Create a webhook and capture an event
On the workflow canvas, add a Webhook trigger and select Create a new webhook.
Enter a name for the webhook and save it. DevRev generates the webhook URL and displays it with a copy control.
Copy the URL and register it in the external system's webhook settings. The exact location varies by system; in GitHub it is under repository settings, in Stripe under developer webhooks.
Return to the trigger and select Listen. DevRev opens a 60-second listening window and captures the events that arrive during it.
While the window is open, cause the external system to send an event. Most systems provide a test or ping action for this; performing the real action, such as merging a pull request, works equally well.
Select an event from the captured list and continue. The list shows each event with the time it was received, so you can identify the one you want to build against.
If the window closes with no events, the trigger returns to its idle state and you can listen again. A window that ends empty usually means the URL was registered incorrectly or the external system did not send during those 60 seconds.
Reuse an existing webhook
Reuse depends on the webhook's creator: they must have added it to a workflow and completed the listening step at least once, and they must then provide the webhook to you.
Ask the webhook's creator to provide the webhook, confirming that they have already used it in a workflow and captured an event on it.
On the workflow canvas, add a Webhook trigger and select Use an existing webhook.
Select the webhook by name. DevRev lists the events already received on that webhook, newest first, aggregated across every workflow that uses it.
Select an event from the list and continue.
(Optional) If none of the listed events represents the case you are building for, listen for new traffic instead and send a fresh event.
Trigger configuration
Continuing from an event opens the trigger configuration, which has three parts: the captured payload, the filter conditions that decide when the workflow runs, and an optional jq transformation.
Sample payload
The sample payload is the body of the event you selected, shown as structured JSON. DevRev parses it into a navigable tree and derives the trigger's output schema from it, preserving the nesting of the original event rather than flattening it. Every field in the tree becomes available to the rest of the workflow.
Field types come from the values in the captured event, so a value sent as a JSON number is typed as a number and one sent in quotes is typed as text. Send test events that match production in both shape and type, particularly where a filter condition or a downstream step compares values.
The payload pane is read-only. To build against a different event, return to the event list and select another one.
Filter conditions
Filter conditions decide whether this workflow runs for a given event. Each condition combines an attribute from the payload, an operator, and an operand, using the same rule builder as the rest of the Workflow Builder. Conditions can be grouped, and a group can be negated so the workflow runs only when the group does not match.
Filters matter most when one webhook carries several kinds of event. A GitHub webhook registered for all repository activity delivers pull requests, issues, comments, and pushes to the same URL; a condition on the field the sender uses to identify the event type narrows the workflow to the case you want, such as merged pull requests only.
Events that fail the filter do not start this workflow. Other workflows reusing the same webhook are evaluated independently.
jq transformation
A jq expression reshapes the payload before it reaches the workflow, selecting, renaming, and flattening the fields you want. The result becomes the trigger's output. This is worth doing when payloads are far wider than the workflow needs — a GitHub pull request event carries a few hundred fields where a workflow may reference five.
The two mechanisms are complementary: jq narrows the data, and filter conditions gate the run. Leave the jq field empty to pass the full payload through unchanged.
Webhook data in downstream steps
Fields captured by the trigger are available to every subsequent step through the variable selector, in the same way as any other trigger's output. Type {{ in any field that accepts a variable, then navigate the trigger's output tree to the value you want.
If a jq transformation is configured, the values available downstream are the transformed ones. If it is empty, the full payload is available with its original structure.
Webhook response
DevRev acknowledges a webhook request as soon as it arrives, before the workflow runs. The sender receives 200 OK with an empty response body, which indicates that the event was accepted and queued, not that the workflow succeeded.
The response carries no information about the resulting run, and a workflow cannot return data to the sender through it. Because the acknowledgment precedes execution, a run that fails partway through does not change what the sender received: the sender sees a successful delivery, and the failure appears in the workflow's run history. Monitor runs in the Runs tab rather than relying on the sender's delivery log to tell you whether the automation worked. See the Monitoring runs section of the Manage workflows article.
URL handling
⚠️ Warning: Treat a webhook URL as a secret. Share it only with the system that needs it, and avoid pasting it into shared documents, tickets, or public repositories.
📝 Note: Authentication options are being added, so that a webhook can require a sender to prove its identity.
Limitations
Webhook support is being extended, and the following constraints apply to webhooks as they work today.
A webhook cannot be deleted after it is created. Plan names accordingly, and stop using a webhook by removing it from the workflows that reference it and unregistering the URL in the external system.
Reuse is not self-service. A webhook is available to another person only after its creator has used it in a workflow, captured an event on it, and provided it to them.
The listening window captures events for 60 seconds. Senders that batch or delay delivery may need more than one listening attempt.
The output schema is derived from one captured event, so fields absent from that event are not part of the schema.
Troubleshooting
Issue: The listening window closes without capturing any event.
Solution: Confirm the URL is registered in the external system exactly as copied, with no trailing characters, then send the event again while the window is open. Check the external system's own webhook delivery log for a failed or unattempted delivery.
Issue: Events arrive on the webhook but the workflow does not run.
Solution: Check the trigger's filter conditions against the payload of a received event. A condition on a field the event does not contain, or a value that differs in case, prevents the run. Confirm the workflow is published.
Issue: The sending system reports successful delivery, but the automation did not complete.
Solution: A successful response means only that DevRev accepted the event. Open the workflow's run history to find the run and the step that failed. If no run exists for the event, the trigger's filter conditions excluded it.
Issue: A run fails at a step that references a webhook field.
Solution: Compare the failing event with the sample the schema was derived from. If the field is absent in production events, either add a filter condition that excludes those events or use a jq transformation to supply the shape the workflow expects.
Common automation patterns
Code review automation
GitHub sends pull request events to one webhook. A filter narrows the run to merged pull requests, and the workflow updates the linked DevRev issue and notifies the team.
Payment processing
Stripe sends a payment event. The workflow extracts the customer and amount, creates a ticket, and posts a confirmation to Slack.
Incident management
PagerDuty sends an event when an incident is created. The workflow creates a ticket with the incident's severity, assigns it to the on-call owner, and starts an escalation timer.
Feedback ingestion
A web form backend sends each submission. The workflow analyzes sentiment and routes the feedback to the responsible product team.
Deployment tracking
A CI pipeline sends an event when a deployment completes. The workflow records the deployment, links the issues it contains, and notifies stakeholders.
Was this article helpful?