Skip to main content
Runcrate posts from the internet, so it cannot reach localhost on your laptop. To build and test a receiver, run it locally, expose it through an HTTPS tunnel, and point an endpoint at the tunnel’s public URL.

Addresses Runcrate will not post to

An endpoint URL must start with https:// and lead to a public address. These are refused when you add the endpoint, and checked again on every delivery:
  • localhost, and names ending in .local, .internal, .home, .lan or .localdomain, or with no dot at all.
  • Private, loopback and link-local IP addresses: 10.x, 172.16.x to 172.31.x, 192.168.x, 127.x, 169.254.x, 100.64.x to 100.127.x, ::1, fc00::/7, fe80::/10 and similar.
  • Any host name that resolves to one of those addresses.
  • A URL with a user name or password in it. Put a secret in the path instead.
The sentence you see says why, for example “This address is only reachable inside your own network. Runcrate posts from the internet.”

1. Run a receiver

This receiver has no dependencies. It checks the signature, prints the event and answers 200. Save it as receiver.mjs:
receiver.mjs
You get the secret when you add the endpoint in step 3. Start the receiver after that:
To build a full handler, use one of the verifiers in verifying signatures instead.

2. Open a tunnel

Any tool that gives localhost:3000 a public https:// URL works. Two common ones:
Copy the https:// URL it prints. Free tunnel URLs usually change each time you start the tool, so update the endpoint when it does.

3. Add an endpoint and send a test event

1

Add the endpoint

In Settings > Webhooks, select Add endpoint, choose Webhook and paste the tunnel URL with your path, for example https://3f2a-198-51-100-7.ngrok-free.app/runcrate/webhooks.
2

Copy the secret

Copy the signing secret shown once, then start the receiver with it (step 1).
3

Send a test event

Select Send a test event. Your terminal prints webhook.test, and Runcrate shows that it was delivered.
Send a test event is in each endpoint’s menu too, so you can send one whenever you change your receiver. It sends a webhook.test event to that endpoint only, whatever events it subscribes to. Nothing happens in your workspace. To see a real event type, trigger it: launch a small instance and terminate it to get instance.ready and instance.stopped. Or replay one from the delivery log with Redeliver. To post an event of any type without Runcrate, sign one by hand with the openssl recipe.

When the test fails

The result, and the delivery log, say what happened in one sentence. The usual ones while testing:

Verifying signatures

Node.js, Python and Go verifiers.

Retries and the delivery log

What each attempt and failure looks like.