What is a webhook relay (and why Docusign needs one)?

A webhook relay is a small service that sits between a source platform (HubSpot, Salesforce, Greenhouse, Coupa) and a destination workflow engine: it accepts the source's outbound webhook, verifies the signature, normalizes the payload, and calls the destination's trigger API with retries and an audit log. Docusign Workflow Builder needs one because its API trigger expects an OAuth-authenticated JSON body keyed to workflow parameter names - not the raw event a CRM, ATS, or procurement tool emits. The relay bridges that gap so you do not write a custom adapter per platform.

What is a webhook relay, exactly? #

A webhook is just an HTTP POST a source system sends when something happens: a deal moves to Closed Won, a candidate accepts an offer, a purchase requisition is approved. A webhook relay is the receiver in front of the destination that does four things every consumer otherwise has to write from scratch:

1. Accept and acknowledge. Return a 2xx fast so the source does not retry unnecessarily.
2. Verify. Confirm the request came from the claimed source using an HMAC signature or an equivalent shared secret.
3. Transform or route. Drop noise, reshape the payload, or pick a downstream target.
4. Deliver reliably. Call the destination, retry on transient errors, and surface the failure when it stops being transient.

The generic version of this exists. Webhook Relay is a public example: it forwards webhooks from one URL to one or more destinations, with optional transformation and HMAC verification helpers. It is a tunnel and a forwarder. That is enough when the destination is a service of your own. It is not enough when the destination is Docusign Workflow Builder.

Why is Docusign Workflow Builder a poor direct webhook target? #

Workflow Builder runs agreement workflows: send a sales contract, route an offer letter, kick off a vendor MSA. To start a run you call the API trigger, which has three properties that make it different from a normal webhook endpoint:

• It needs an OAuth bearer token for your Docusign account. Not a static API key. Token refresh, scope grants, and key rotation are your problem.
• The body must match workflow-specific parameter names. You discover those names per workflow via the getWorkflowTriggerRequirements endpoint. A HubSpot deal payload calls the buyer properties.email. Workflow Builder might call the same field signerEmail. The names will not line up.
• It is not a webhook receiver. Workflow Builder does not expose a generic inbound URL you can paste into HubSpot. It expects an authenticated client to call its REST API.

So if HubSpot, Salesforce, or Greenhouse fires a webhook and you want Workflow Builder to start a run, something in the middle has to: catch the webhook, hold Docusign credentials, look up the workflow's trigger schema, reshape the payload, and call the API. That something is the relay.

What are the four jobs of a Docusign-aware webhook relay? #

A relay built for Docusign Workflow Builder has to do everything a generic forwarder does, plus the Docusign-specific work. Four jobs:

1. Signature verification per source #

Every source platform signs webhooks differently. HubSpot v3 sends X-HubSpot-Signature-v3 and X-HubSpot-Request-Timestamp, rejects requests older than 5 minutes, and uses HMAC SHA-256 over method + URL + body + timestamp. Salesforce Outbound Messages do not include an HMAC signature at all and rely on Org ID for identity, so authenticity has to be enforced another way (mutual TLS, IP allowlist, or a custom Apex callout that does sign). The relay needs to know each source's scheme.

POST /webhooks/hubspot HTTP/1.1
X-HubSpot-Signature-v3: 4f...c2
X-HubSpot-Request-Timestamp: 1714835200000
Content-Type: application/json
 
{"objectId": 9911, "propertyName": "dealstage", "propertyValue": "closedwon"}

2. Workflow parameter mapping #

Every workflow in Workflow Builder declares its own input shape. The relay has to fetch that shape and map source fields to parameter names. If you do this by hand, you maintain a translation table per workflow, per source. If you do it by name match, you constrain workflow authors to use parameter names that match the source's payload keys, which is the simpler contract.

3. Docusign-side authentication #

The relay holds and refreshes the OAuth token to the Docusign account. Source platforms do not. This is the credential boundary: a leaked HubSpot webhook URL should never give an attacker the ability to send envelopes. That only stays true if the source side does not hold Docusign credentials.

4. Retries, idempotency, and the failure log #

Workflow Builder calls can fail for boring reasons: rate limits, transient 5xx, a workflow that was just renamed. The relay needs to retry with backoff, deduplicate by source event ID, and write every attempt to a log a human can read at 11pm on a Friday. This is the operational layer most teams under-build and then regret. We wrote a longer piece on the failure modes in Why Docusign webhooks fail silently.

Generic webhook relay vs Docusign-specific relay #

A generic relay is a pipe. It forwards bytes, optionally transforms them with a script, and gives you a URL. That is the right tool for "I want my home server to receive GitHub pushes." It is the wrong tool for "a closed-won HubSpot deal should start a Workflow Builder run on the right account, with the right parameters, with retries, and with an audit log my legal team can read."

Side by side:

The last row is the one that bites teams in production. Docusign Connect is the outbound webhook from Docusign about envelope events (signed, voided, declined). A Workflow Builder API trigger is the inbound call that starts a workflow. They are different failure domains. A generic relay cannot tell you which one broke.

When should you build your own webhook relay? #

Build it yourself when:

• You have one source, one workflow, and the team to own retries, signature verification, OAuth refresh, and observability forever. That is the honest cost. A first version takes an afternoon. A production version takes weeks across the team's lifetime.
• Your source signs with a non-standard scheme that no off-the-shelf relay supports.
• Your compliance posture requires the relay to run in a network you control end-to-end.

Buy or borrow when:

• You have more than one source platform. The combinatorics of N sources times M workflows is where bespoke code goes to die.
• Workflow authors should not need to file an engineering ticket to change a payload mapping.
• You want the silent failure surface to be someone else's on-call rotation.

The deeper version of this calculus - including how it interacts with Docusign IAM platform decisions - lives on the fluidlabs resources hub.

Where does Baton fit in this picture? #

Baton is the production-grade webhook relay between source platforms and Docusign Workflow Builder. It does the four jobs above with one opinionated rule: payload fields are matched to workflow parameter names automatically, so there is no JSONPath UI, no drag-and-drop mapping, and no per-workflow translation file. You name your Workflow Builder parameters to match the source's field keys (or you rename them once), and Baton handles the rest.

What that looks like in practice:

1. You connect Docusign to Baton once. Baton holds the OAuth token.
2. You generate a webhook URL per source in Baton's Command Center.
3. You paste that URL into HubSpot, Salesforce outbound messaging, Greenhouse, Coupa, Zoho - wherever the event lives.
4. When the source fires, Baton verifies the signature, finds the matching workflow by parameter shape, and calls the Workflow Builder API.
5. Every attempt - success, retry, dead-letter - shows up in the Action log.

A few things Baton deliberately does not do, because they are the source of most "wait, why did this trigger?" incidents:

• It does not store source-platform API keys or run OAuth flows to HubSpot, Salesforce, or anywhere upstream. Webhook URLs only.
• It does not push signed documents or envelope status back into the source CRM. Write-backs happen on the Docusign side using Workflow Builder Extension Apps, which is a different failure domain.
• It does not trigger envelopes directly. It triggers workflows, and those workflows create envelopes. The distinction matters when you are debugging a missing signature request.

If the integration you want is already shipped, the canonical examples are HubSpot and the rest of the Baton resources index. If your source is on the roadmap (Salesforce, Zoho CRM, Pipedrive at the time of writing), the architectural pattern in this article is what Baton implements.

What to do next #

If you are wiring a CRM, ATS, or procurement tool to Docusign Workflow Builder and you have read this far, the next step is concrete: start with Baton, or read the silent failures piece first if you want to see what production breakage actually looks like.