API keys and webhooks

Your site can work with other systems, such as a CRM, a booking system or an automation tool. An API key lets another system read and change your site’s content. A webhook sends another system each form or conversion the moment it happens. Who can do this: Admins and Owners. You create keys and webhooks in the CMS. The developer building the other system gets everything else from the developer docs: Quickstart, Authentication and Signing requests.

Before you start

• Ask the developer or the service what it needs: which parts of your site it reads or changes, or which events it wants to hear about.
• Have somewhere safe ready to paste a secret, such as a password manager. Keys and secrets are shown only once.

Create an API key

Manage your keys

The API Keys list shows each key’s Label, Key ID, whether it’s Enabled, and when it was Last used. Open a key to change it. Its Settings, Security and Details tabs hold the same choices you made when you created it.

• Stop a key at once: turn off Enabled and save. Its record stays, so you can turn it back on.
• Lost the token, or worried it leaked? It can’t be shown again, so open the key’s menu (⋯) and choose Rotate key. The key gets a new token and a new signing secret, shown once, and the old ones stop working at once. Its label, scopes and security settings stay the same. Give the new token to the developer straight away.
• You can give only what you have. A key can’t hold a scope your own role doesn’t allow. A pack that needs one stays in the list but can’t be picked, and it says which scopes it needs.

Scope Packs

A Scope Pack is a named set of scopes, so a key for a common job takes one pick instead of a dozen checks. Open them with the Scope Packs button at the top of Manage API Keys, or from the command palette with Scope Packs. The shortcut is G then Shift+K. The API Keys button at the top of Scope Packs takes you back.

• Default packs come with your site, one for each Recipe in these docs, such as Site translation or Content rewrites. The Kind column says Default, or Default (edited) once someone has changed one.
• Make your own: choose New Scope Pack, give it a Name and a short Description, check its Scopes and save. It’s in the list on the Create API Key window from then on.
• Change or remove a pack like any other item. A key made from a pack keeps its own scopes: changing or deleting the pack never changes a key.
• Packs follow your role, too. A pack can only hold scopes you could give a key yourself. A pack holding one you can’t give opens read-only for you, so only someone who holds those scopes can change or remove it.
• Put the defaults back: choose Restore default packs. Deleted default packs come back and edited ones go back to how Fetchski ships them. Packs you made yourself aren’t touched.

Send events with a webhook

Send a form to a webhook

A form can also pick a destination itself. In the form’s editor, open the Actions tab, add Send to webhook, and choose the Webhook destination. This works even if the destination doesn’t subscribe to Form submitted. Each submission reaches a destination once, however it was chosen. See Build a form.

Check deliveries

Open a destination and go to its Deliveries tab. It lists recent deliveries, newest first, kept for 30 days: when, the event, its status and the other system’s answer.

• Send test event sends a sample now and shows the answer. It works even while the destination is paused or off.
  • It worked: you see “Test delivered — the receiver answered HTTP 200 in …”, with a number and a time. Any answer in the 200s is a success.
  • It didn’t: you see “Test not delivered:” followed by the reason. The same reason shows in the delivery’s row in the list.
  • What to fix yourself: a mistyped URL, or an event or filter you didn’t mean to set. Anything else, such as the other system refusing the sample, send to that system’s developer with the reason shown.
• Rotate signing secret makes a new secret, shown once. The old one keeps working beside it for 24 hours, so the other system can switch over without missing anything.
• Refresh loads the latest deliveries.

When deliveries fail

If the other system doesn’t answer, Attract tries again: up to 7 attempts over about a day and a half. If every attempt fails:

• the destination is paused, and its Deliveries tab says why;
• new events wait for it, as Held (paused);
• everyone who manages webhooks gets a notification.

Some problems pause it at once, with no retries, such as an address that isn’t allowed or a broken custom header. Fix the cause, use Send test event to check, then choose Resume. Everything held is sent again.

Good to know

• Switching a destination off with Enabled cancels anything it still had waiting.
• Custom headers and Allow private network are advanced settings on the Advanced tab. Leave them as they are unless the other system’s administrator gives you values for them.
• Custom headers: extra details sent with every delivery, such as a password the other system asks for. Add exactly what its administrator gives you. Values are hidden once saved.
• Allow private network stays off unless the other system runs on the same private network as your site, such as a service on the same server. While it’s off, Attract refuses addresses inside private networks.
• A webhook never holds up your site. A delivery problem never stops a form from sending or a conversion from being recorded.

Troubleshooting

Related