Skip to content
Micro micro
Go to Micro
API Reference
Webhooks

Create a webhook

client.Webhooks.New(ctx, params) (*WebhookWithSecret, error)
POST/v2/webhooks/{teamId}

Registers a webhook and enqueues an asynchronous verification handshake (run by the dispatcher). The response includes the signing secret, shown only this once; verified is false until the handshake passes.

ParametersExpand Collapse
params WebhookNewParams
TeamID param.Field[string]Optional

Path param

formatuuid
WebhookCreate param.Field[WebhookCreate]

Body param: On create, the dispatcher asynchronously runs a verification handshake: it sends a GET to url with micro_hook_mode=subscribe, a one-time micro_hook_challenge, and the webhook’s micro_hook_token. The endpoint must respond 200 and echo the challenge value verbatim in the body; on success the webhook’s verified flag flips to true. A failed handshake does not fail creation — re-run it later via the verify endpoint.

ReturnsExpand Collapse
type WebhookWithSecret struct{…}

Returned ONLY on creation. Includes the signing secret (shown once) and the pending verification status.

Secret string

HMAC signing secret (prefix whsec_). Store it now — it is never returned again. The dispatcher signs each delivered payload with it so your endpoint can verify authenticity.

Verification WebhookWithSecretVerificationOptional

Status of the verification handshake enqueued by this request. The handshake runs asynchronously in the dispatcher; poll the webhook (its verified flag flips to true on success) to observe the outcome.

Status WebhookWithSecretVerificationStatus

Always pending at the moment of the response — the dispatcher has been asked to run the handshake but has not reported back yet.

Create a webhook

package main

import (
  "context"
  "fmt"

  "github.com/micro-so/micro-sdk-go"
  "github.com/micro-so/micro-sdk-go/option"
)

func main() {
  client := micro.NewClient(
    option.WithAPIKey("My API Key"),
    option.WithTeamID("My Team ID"),
  )
  webhookWithSecret, err := client.Webhooks.New(context.TODO(), micro.WebhookNewParams{
    WebhookCreate: micro.WebhookCreateParam{
      Name: micro.F("x"),
      URL: micro.F("https://example.com"),
    },
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", webhookWithSecret)
}

{
  "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  "created_at": "2019-12-27T18:11:19.117Z",
  "enabled": true,
  "name": "name",
  "team_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  "url": "https://example.com",
  "verified": true,
  "description": "description",
  "updated_at": "2019-12-27T18:11:19.117Z",
  "verification_token": "verification_token",
  "verified_at": "2019-12-27T18:11:19.117Z",
  "secret": "secret",
  "verification": {
    "status": "pending"
  }
}
Returns Examples
{
  "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  "created_at": "2019-12-27T18:11:19.117Z",
  "enabled": true,
  "name": "name",
  "team_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  "url": "https://example.com",
  "verified": true,
  "description": "description",
  "updated_at": "2019-12-27T18:11:19.117Z",
  "verification_token": "verification_token",
  "verified_at": "2019-12-27T18:11:19.117Z",
  "secret": "secret",
  "verification": {
    "status": "pending"
  }
}