Skip to main content
An event trigger starts a workflow when an external system sends a signed HTTP request to a trigger-specific endpoint. Skyvern verifies the signature, maps values from the JSON body to workflow inputs, records the delivery, and dispatches the run asynchronously.

Create a trigger in Studio

  1. Open the workflow in Studio and select Triggers in the top bar.
  2. Select Add, then map any workflow inputs to fields in the request body.
  3. Save the endpoint URL and signing secret. The URL stays available in the trigger’s Setup tab; the secret is shown only when the trigger is created or its secret is rotated.
Only organization admins can create or manage triggers, rotate secrets, and replay deliveries. Trigger management is available in Studio; there are no public SDK management methods yet.

Map the event body

Mappings use JSON Pointer (RFC 6901). Each workflow input maps to a pointer into the incoming JSON object. For example, for this body:
map order_id to /order/id and customer_email to /order/customer/email. Pointers must start with /; in a key name, encode ~ as ~0 and / as ~1.

Send a signed request

Send a POST to the endpoint URL from Studio with these headers: Calculate the HMAC with the UTF-8 bytes of the trigger secret as the key. Sign the exact raw request body bytes, prefixed with the UTF-8 bytes of v1:{timestamp}:{event_id}::
The body must be a JSON object no larger than 256 KB. Do not parse and re-serialize a body after signing it; send the same bytes that were signed. These are inbound event-trigger signatures. They differ from Skyvern’s outbound webhook signature, which uses a different header convention and key. Do not use the outbound webhook verifier for event triggers. Set the endpoint URL and secret from Studio in your environment. Keep the secret out of source control and logs.
Each example below creates a new event ID. For retries of the same source event, persist and reuse its event ID and body; generate a fresh timestamp and signature for each attempt.

Responses and retries

If a request times out or you do not receive a response, retry with the same event ID and exact same body. This lets Skyvern return the existing delivery instead of creating a second one. Refresh the timestamp and signature on every attempt. Do not retry a 422 unchanged; use Studio replay after correcting the mapping.

Delivery log and replay

In Studio, open the trigger and select Deliveries to see the delivery status, reason, payload size and SHA-256, and any linked run. The event body is not shown. Organization members can read delivery metadata; only admins can replay a rejected delivery. Replay uses the stored payload and applies the trigger’s current mapping. If the stored payload has expired, it cannot be replayed.

Retention and secret rotation

The request payload is encrypted at rest. It is retained for 30 days by default. For organizations with a configured data-retention period, that period applies with a 7-day minimum; it may be shorter or longer than 30 days. Retention applies to the stored trigger payload; values copied into workflow run inputs follow the normal run-data retention policy. Rotating a trigger secret is an immediate cut-over: the old secret stops working as soon as rotation completes, with no overlap period. Update every sender with the new secret shown in Studio when you rotate it.