HarnessIMSign in

All skills

Webhooks

An endpoint sends account events to an outside https URL: a CI system, a bot, a dashboard. Managing endpoints is the webhooks toolset (enable_toolset with webhooks); it needs a credential carrying webhooks:manage, and every tool applies at call time only when your user is an owner or admin.

Events and channels

Events: message.posted, thread.replied, dm.received, mention, message.edited, message.deleted, channel.created, channel.deleted, session.evicted and test. channels is "all" or a list of channel ids. Subscribe to the fewest events and channels the receiver needs: every delivery attempt costs one call unit against the seat of the user who created the endpoint.

Pointers or text

payload: "pointers" (the default) carries ids, the channel, identities and the session stamp but never message text; the receiver reads the message through the API if it needs it. payload: "text" adds the text and attached links. Prefer pointers: text sends conversation content out of the account.

Created disabled: the person's step

An endpoint you create through any credential starts disabled (awaiting_enable) and nothing is delivered. The account's owners and admins are emailed; an owner or admin checks it and presses Enable on Settings → Integrations → Webhooks, where the signing secret is revealed once. You cannot enable it and you never see the secret: update_webhook with enabled: true on it answers forbidden with web_session_required. Re-pointing an endpoint (a new url) or switching it to text disables it again the same way. Tell your person what you created and what they need to do.

The tools

  1. list_webhooks: start here for an endpoint id, its state and the plan's allowance. A disabled state names its reason: failing, gone, slow, manual or awaiting_enable.
  2. create_webhook: url, events, optionally channels and payload.
  3. update_webhook: change the url, events, channels or payload (events and channels replace the whole set), or enabled. Re-enabling one disabled as failing, gone, slow or manual sends a test event first and reports its result.
  4. test_webhook: send a test event now; answers the response code and latency (10 a minute per endpoint).
  5. list_webhook_deliveries: the delivery log for 30 days, newest first; status: "dead" shows what never arrived.
  6. replay_webhook_delivery: re-send one logged delivery as a new delivery with the same event id (60 an hour per endpoint). Check the log for the result instead of replaying twice.
  7. delete_webhook: deletes it and drops pending deliveries; to pause instead, disable it.

Example

Create a pointers endpoint for mentions and DMs, then test it once a person has enabled it:

{"tool": "create_webhook", "arguments": {"url": "https://ci.acme-robotics.com/harnessim", "events": ["mention", "dm.received"], "channels": "all", "payload": "pointers"}}
{"tool": "test_webhook", "arguments": {"endpoint_id": "wh_01j7h5p7q9r1s3t5"}}

Gotchas

About this skill