Webhook triggers

A webhook trigger turns an inbound HTTP request into an agent job. Point an external system (a Git host, a monitoring tool, a ticketing system) at a trigger URL, and each delivery that passes verification creates a job for the associated agent.

How it works

  1. An external system sends an HTTP POST request to the trigger’s inbound URL, shown as Inbound URL on the agent’s Triggers tab.
  2. BridgeMCP verifies the delivery with the method its provider uses: an HMAC signature, a public-key signature, a shared token, or an HTTP Basic Auth credential. A delivery that fails verification is rejected with 401 and creates no job.
  3. On success, a new job is created asynchronously for the agent and enters the Queued state.
  4. The agent runs the job in its own isolated workspace and reports a result.

Because job creation is asynchronous, the caller gets a fast acknowledgement and does not wait for the agent to finish.

Authentication

Every delivery is verified before a job is created. The method depends on the provider you pick when you add the webhook on the agent’s Triggers tab: most providers sign deliveries with an HMAC, SendGrid and Discord sign them with a private key, Datadog sends a shared token, and Postmark sends an HTTP Basic Auth credential. The console shows the provider’s method under Verification and asks for the value it needs under that provider’s label, such as Signing secret, Shared token, or Application public key. A webhook cannot be saved without this value. It is stored encrypted, and the console only shows whether one is configured.

BridgeMCP answers 401 Invalid webhook signature and creates no job when the signature, token, or credential is missing or does not match, when a signed timestamp is more than 5 minutes from BridgeMCP’s clock (Stripe, Paddle, Mailgun, and Slack), or when the trigger has no usable stored value. Slack’s URL verification challenge and Discord’s PING are answered only after they pass the same check, and neither creates a job.

Verification by provider

ProviderValue you enterHow BridgeMCP verifies a deliveryCovers the payload
Generic HTTPSigning secretHMAC-SHA256 of the raw body, sent in X-Bridge-Signature as sha256= plus lowercase hexYes
StripeSigning secretHMAC-SHA256 of the timestamp and body in Stripe-Signature, timestamp within 5 minutesYes
GitHubWebhook secretHMAC-SHA256 of the raw body in X-Hub-Signature-256Yes
PagerDutySigning secretHMAC-SHA256 of the raw body in X-PagerDuty-SignatureYes
JiraWebhook secretHMAC-SHA256 of the raw body in X-Hub-SignatureYes
SentryClient secretHMAC-SHA256 of the raw body in Sentry-Hook-SignatureYes
DatadogShared tokenThe X-Datadog-Webhook-Token header must equal the stored tokenNo
LinearSigning secretHMAC-SHA256 of the raw body in Linear-SignatureYes
ZendeskSigning secretHMAC-SHA256 of the timestamp and body in X-Zendesk-Webhook-SignatureYes
IntercomClient secretHMAC-SHA1 of the raw body in X-Hub-SignatureYes
ShopifySigning secretHMAC-SHA256 of the raw body in X-Shopify-Hmac-SHA256Yes
TwilioAuth tokenHMAC-SHA1 of the request URL and sorted form parameters in X-Twilio-SignatureYes, for form parameters; a JSON body only when the URL carries bodySHA256
NotionVerification tokenHMAC-SHA256 of the raw body in X-Notion-SignatureYes
PaddleSigning secretHMAC-SHA256 of the timestamp and body in Paddle-Signature, timestamp within 5 minutesYes
SendGridVerification keyECDSA P-256 signature of the timestamp and body in X-Twilio-Email-Event-Webhook-Signature, checked with SendGrid’s public keyYes
PostmarkBasic auth credentialThe Authorization header must equal the stored value, which you enter as the full header (Basic and the base64 credentials)No
MailgunSigning keyHMAC-SHA256 of the timestamp and token in the body’s signature object, timestamp within 5 minutesNo
SlackSigning secretHMAC-SHA256 of v0:, the timestamp, and the body in X-Slack-Signature, timestamp within 5 minutesYes
DiscordApplication public keyEd25519 signature of the timestamp and body in X-Signature-Ed25519, checked with the application public keyYes

What verification protects

Verification always authenticates the caller: BridgeMCP accepts a delivery only from a sender that holds the configured secret, token, or credential, or the private key that matches the configured public key. Whether it also detects a modified payload depends on the method:

  • Signatures over the payload (SendGrid, Discord, and every HMAC provider except Mailgun) fail if the payload was changed after it was signed. Twilio’s signature covers the form parameters, and a JSON body only when the URL carries bodySHA256.
  • Datadog’s shared token and Postmark’s Basic Auth credential are compared as sent and do not cover the body, so they do not detect a modified payload.
  • Mailgun’s HMAC covers the timestamp and token values in the body’s signature object, not the event data, so it does not detect a modified payload either.

Keep secrets, tokens, and credentials confidential: anyone who holds one can send deliveries that pass verification and queue jobs for the agent. SendGrid’s verification key and Discord’s application public key are public keys and cannot be used to sign a delivery. To change a stored value, select the webhook on the Triggers tab and choose Replace next to Signing secret.

Passing data to the job

The webhook payload becomes the job’s input, so the agent can act on the event that triggered it: the pull request that opened, the alert that fired, the ticket that was created. Design the agent’s skills around the shape of the payload you expect.

Next steps