Origin Secret
The pipeline key in your tag is visible to anyone who opens your page, so on its own it cannot stop someone sending events straight to your collection endpoint. When your own proxy or CDN sits in front of that endpoint, an origin secret closes the gap: the proxy adds a secret header to every request it forwards, browsers never see it, and with enforcement on Signal refuses any request that does not carry it.
How it works
- Your proxy adds
X-DFSignal-Origin-Secret: <secret>to every request it forwards to Signal. - With enforcement on, a request without the header, or with a different value, is refused with HTTP 403.
- The secret is stored encrypted and shown once, when it is set. Nobody can read it back afterwards.
- Each pipeline has its own secret.
Set it up
- Open the pipeline, then Settings → Origin secret, and select Generate secret. Copy the header it shows.
- Add the header to your proxy’s requests to Signal. In Cloudflare, use a request header Transform Rule that sets a static header on your collection path, or set it in a Worker before the request is forwarded. On other CDNs and load balancers, add it as a request header on the origin request.
- Send a test event and check that it arrives, for example in the Event Debugger.
- Select Enforce.
Enforce only once your proxy sends the header. Until then, every request would be refused.
Rotate the secret
Select Rotate secret and choose how long the current secret stays valid: 1 hour, 24 hours, 3 days, 7 days, or no overlap. Signal accepts both secrets until then, so no request is refused while you update the proxy. Once the proxy sends the new secret, select Stop accepting it now, or let the overlap run out.
Move a pipeline to another environment
Secrets never travel in an exported pipeline configuration. In the new environment, open Origin secret, tick Use a secret I already have and enter the same secret, so the proxy keeps its header. An import never turns on enforcement for a pipeline that has no secret yet: the import says so, and you turn it on once the secret is set.
API
| Method and path | What it does |
|---|---|
GET /v1/admin/pipelines/{id}/origin-secret | Status: whether a secret is set and enforced, and until when a rotated-out secret is still accepted |
POST /v1/admin/pipelines/{id}/origin-secret | Generate a secret, or set {"secret": "..."}; overlap_hours (0 to 720, default 24) keeps the replaced secret valid. The only response that returns the secret |
PUT /v1/admin/pipelines/{id}/origin-secret/enforce | {"enforce": true} or false. Refused while no secret is set |
DELETE /v1/admin/pipelines/{id}/origin-secret/previous | Stop accepting the rotated-out secret now |
DELETE /v1/admin/pipelines/{id}/origin-secret | Remove the secret. Refused while it is enforced |
A secret you set yourself must be 32 to 256 characters of letters, digits and . _ ~ + / = -. Every change is recorded in the audit log, without the secret.
With trusted proxies
The origin secret proves a request came through your proxy. Trusted proxies are a separate setting: they tell Signal which hops may report the visitor’s IP address. Use both when a proxy sits in front of Signal.