Creating Webhooks

Creating a webhook takes a few minutes: you open a dialog, fill in the fields, and click Create. Monime starts sending events to your endpoint straight away. This guide walks through every field, what it controls, and why it matters, so whoever creates the webhook, a developer or someone on the operations team, configures it correctly.

Open the create dialog

1. Go to Developer > Webhooks. The page lists your webhooks, or shows an empty state if you have none.
2. Click Create webhook (top right).
3. The Create Webhook dialog opens in full screen.

You can also open it by adding ?create=true to the webhooks URL.

Basic information

Name

Required, 1 to 100 characters. A label that identifies the webhook in the list and on its details page. Describe its purpose or destination, so the right webhook is easy to find once you have several:

• By purpose: "Checkout Session to CRM"
• By environment: "Production Payments to Accounting"
• By system: "Analytics Pipeline"

Avoid generic names like "Webhook 1" or "Test".

URL

Required. The HTTPS endpoint that receives deliveries, up to 255 characters. For example, https://example.com/api/webhooks/monime.

If the URL breaks a rule, the dialog shows an error and the Create button stays disabled. If a URL looks right but is still rejected, check for extra spaces, missing slashes or a wrong port.

Enable

Default: enabled. An enabled webhook receives events as soon as it is created. Turn it off to finish setting things up before events start arriving, then enable it from the details page. A disabled webhook keeps its configuration; Monime simply sends it nothing.

Verification method

Required. Every delivery is signed, so your endpoint can prove it came from Monime. Without verification, anyone who discovers the URL could send fake events. See Verification and security for the code.

HMAC-SHA256

A secret shared between you and Monime. Monime signs each delivery with it, and your server computes the same signature and compares.

• The dialog generates a random secret. Click Regenerate for a new one, or paste your own.
• The secret must be 32 to 100 characters; the Create button stays disabled until it is.
• Store the secret securely: your server needs it to verify the monime-signature header.

ECDSA P-256

Asymmetric signing. Monime signs with a private key only it holds, and you verify with the public key.

• Monime generates the key pair. The public key appears on the webhook details page after creation.
• Because only Monime can produce a valid signature, ECDSA also gives non-repudiation: you can prove to a third party that Monime sent a request. HMAC can't, because both sides hold the secret.

Most integrations use HMAC-SHA256: it is simpler to implement and enough for most needs.

Failure notification

Optional. Up to two email addresses that receive an alert when deliveries fail repeatedly, for example when:

• The endpoint is unreachable (DNS failure, timeout, connection refused).
• The endpoint keeps returning a non-2xx status.

Use a team inbox or distribution list, so alerts still reach someone when a person is away. An active webhook with no alert emails shows a warning in the list.

API release

Required. The release defines which events exist and the structure of their payloads. Within a release, Monime only adds fields and events; breaking changes happen only in a new release. Choose the release your endpoint's code expects: the wrong one means payloads your server doesn't understand.

Events

Required: 1 to 100 events from the selected release.

• Click the field to open the list, and search by name.
• Selected events appear as tags.

Common choices:

See Events and payloads for every event in each release.

• Start with a small set and add more once deliveries work.
• If one endpoint handles several events, group them by handler.
• Your endpoint should return a 2xx even for events it ignores: an error triggers retries for events you never needed.

Custom headers (optional)

Up to 10 HTTP headers sent with every delivery. The usual reason is authentication: your endpoint can check a token before it verifies the signature.

• Names may contain only letters, digits and hyphens ([A-Za-z0-9-]+).
• Values must be printable ASCII (space and tab allowed), with no control characters.

Create the webhook

The Create button is enabled only when:

• The name is not empty
• The URL is valid
• An API release is selected
• At least one event is selected
• The failure-notification list has no more than two valid email addresses
• For HMAC-SHA256, the secret is 32 to 100 characters

Click Create. The dialog closes and the new webhook appears in the list.

Check that it works

1. Open the webhook from the list and scroll to Event Deliveries.
2. Trigger an event you subscribed to, for example with a test payment.
3. Wait a few seconds, then refresh.
4. Confirm a delivery appears with status Success.

If the delivery shows Failed or Scheduled, open it to see the HTTP code and payload; see Monitoring and debugging. If nothing appears, check that the webhook is enabled and that the event you triggered is one you subscribed to.

Common mistakes

Next steps

• Managing webhooks
• Verification and security
• Events and payloads