Manage signed webhooks

Webhooks send a small message to another system whenever certain Metra records change. Include the record ID in that message so the receiving system can load the latest record if needed.

Open Integrations > Webhooks.

Only owners and administrators can create or change webhook settings. You must be signed in to your account to do this; an API key cannot create, change, or re-send webhooks.

Prepare the receiver

Use a public HTTPS URL for the receiver. Metra rejects URLs with credentials, redirects, unsupported addresses, and private/local/cloud-metadata destinations.

Your receiver should return a 2xx status quickly. If it needs to do longer work, place that task on its own internal queue.

Before processing an event, the receiver should:

1. Read the incoming message exactly as received. Do not parse and re-build it before verification.
2. Reject timestamps outside the documented tolerance.
3. Compute the HMAC-SHA-256 signature using <event-id>.<timestamp>.<raw-request-body> and the signing secret.
4. Compare the decoded signatures in constant time.
5. Deduplicate using Metra-Webhook-Id before applying work.

The request includes:

• Metra-Webhook-Id
• Metra-Webhook-Timestamp
• One or more versioned Metra-Webhook-Signature values

Check API and webhook documentation for examples and the current event list.

Create and verify an endpoint

1. Select Create webhook and enter a descriptive name and the public HTTPS receiver URL.
2. Select only the events that the external system needs.
3. Create the endpoint, then copy the signing secret into your secure secrets store immediately. Metra shows the full secret once; it cannot show it again.
4. Acknowledge that the secret is stored.
5. Select Verify. Metra sends a signed verification challenge to the same endpoint path used for real deliveries. The endpoint is active only when the receiver answers correctly.

Changing the destination URL sets the endpoint back to pending verification. Verify the new URL before expecting deliveries.

Understand delivery behaviour

Delivery is at least once. The same event ID may arrive more than once after a timeout or retry. Events are not guaranteed to be delivered in strict order, so use the event ID to avoid processing a duplicate and always load the current state for safety.

Metra retries delivery when it receives transport errors, timeouts, rate limits, or server failures. If failures continue, the endpoint can move to a failing or paused state.

Open Deliveries and filter by status or event type. You can see safe delivery details, including attempt number, timing, status code, result code, and receiver request ID. Payload details, signing secrets, and response bodies are not shown.

Rotate a signing secret

Use Short overlap for planned key rotation. During overlap, Metra sends both old and new signatures so the receiver can accept either while you switch keys. Remove the old secret before its retirement time.

Use Immediate cutover if the secret may be exposed. The old secret stops working immediately. Save the new secret before you close the panel.

Pause, resume, redeliver or revoke

• Pause an endpoint before receiver maintenance or while investigating failures.
• Resume it after the receiver is healthy and ready to accept any queued deliveries.
• Redeliver an eligible retained delivery only if your receiver checks event IDs and skips duplicates. Redelivery keeps the same event ID and creates a new delivery attempt record.
• Revoke an endpoint when the integration is retired or its ownership is unclear. Revocation is irreversible, but retained audit and delivery history remain available.

Every manual lifecycle change requires a reason and is retained in the audit trail.

Troubleshooting safely

• A pending endpoint has not completed the signed verification challenge, or its URL changed.
• A failing endpoint has consecutive delivery failures; inspect result codes and the receiver’s own logs.
• A request may be a retry even after your receiver already completed the work. Deduplicate before applying changes.
• Share the event ID, delivery ID, result code and trace ID with support. Never share the signing secret, signature header or raw sensitive receiver logs.
• If Webhooks is unavailable, ask an owner or administrator to review your organisation permissions.