Documentation

User documentation & integration guide

Key capabilities

• 100% Atlassian Cloud security: runs entirely inside the Atlassian Forge execution sandbox — no third-party servers or proxy databases outside your Atlassian Cloud trust boundary.
• Multi-provider ingestion: native auto-detection and payload formatting for GitHub, Datadog, PagerDuty, Grafana, AWS SNS, Sentry, GitLab, and custom JSON payloads.
• Zero Automation costs: bypasses Jira Automation limits by ingesting HTTP POST requests via Forge web triggers.
• Token & secret authentication: header-based, Bearer token, and query-parameter authentication, with write-only secret storage in Atlassian's Key-Value Store (KVS).
• Built-in deduplication: automatically deduplicates duplicate webhook deliveries using provider-native delivery IDs (x-github-delivery, x-amz-sns-message-id, x-pagerduty-webhook-id).

Quick setup

Setting up ForgeHook takes less than two minutes.

1. Open the ForgeHook configuration screen

1. Log in to your Jira Cloud instance as a Jira Administrator.
2. Go to Jira Settings (⚙️) → Apps → ForgeHook Webhook Router.
3. Alternatively, select ForgeHook Settings from any Jira project sidebar.

2. Configure routing rules

• Destination Jira project: the project where incoming alerts should create issues.
• Default issue type: the target Jira issue type (e.g. Task, Bug, Incident, Story).
• Summary prefix: an optional prefix prepended to auto-generated issue titles (e.g. [Alert]).
• Shared secret / token: enter a custom secret or click Generate Secure Token for a 256-bit cryptographically secure hex secret.

3. Copy your webhook endpoint URL

After saving, your unique Atlassian-hosted endpoint URL is displayed:

https://<unique-id>.hello.atlassian-dev.net/x1/<web-trigger-token>

Paste this endpoint into your monitoring tools, CI/CD pipelines, or third-party webhooks.

Integration guides

Custom HTTP POST (JSON)

ForgeHook automatically parses any incoming JSON body and extracts the best issue title candidate.

curl -X POST "https://<your-forgehook-endpoint-url>" \
  -H "Content-Type: application/json" \
  -H "x-forgehook-token: YOUR_CONFIGURED_SHARED_SECRET" \
  -d '{
    "title": "High CPU Usage Warning on prod-worker-01",
    "message": "CPU utilization exceeded 95% threshold for 5 consecutive minutes.",
    "severity": "CRITICAL"
  }'

GitHub webhooks

1. Go to your GitHub repository → Settings → Webhooks → Add webhook.
2. Payload URL: your ForgeHook endpoint URL.
3. Content type: application/json.
4. Secret: your configured shared secret.
5. Select the events to trigger the webhook (e.g. workflow runs, push events, issue comments).

Datadog alert webhooks

1. In Datadog, go to Integrations → Webhooks → New Webhook.
2. Name: Jira-ForgeHook
3. URL: your ForgeHook endpoint URL.
4. Custom headers: {"x-forgehook-token": "YOUR_CONFIGURED_SHARED_SECRET"}
5. Save, then reference @webhook-Jira-ForgeHook in your monitor notifications.

PagerDuty webhooks

1. In PagerDuty, go to Integrations → Generic Webhook (v3).
2. Endpoint URL: your ForgeHook endpoint URL.
3. Add custom header: x-forgehook-token: YOUR_CONFIGURED_SHARED_SECRET

Grafana / Prometheus Alertmanager

1. In Grafana, go to Alerting → Contact points → Add contact point.
2. Select type Webhook.
3. URL: https://<your-forgehook-endpoint-url>?token=YOUR_CONFIGURED_SHARED_SECRET
4. Attach the contact point to your notification policies.

Authentication methods

ForgeHook enforces strict authorization on all inbound webhook requests. Pass your configured shared secret using any of the following channels:

Troubleshooting & response codes

ForgeHook returns standard HTTP status codes and sanitized JSON error payloads with correlation IDs for debugging.

Privacy & data handling

• No remote storage: ForgeHook operates entirely inside Atlassian Cloud. Webhook payloads are processed in-memory and discarded immediately after creating the Jira issue.
• Data residency: all data stays within your Atlassian Jira Cloud region.
• Audit logging: ForgeHook records client IP metadata (source IP/host) in the Jira issue description for security auditing.

See the full Privacy Policy for details.

Support & feedback

Need help or want to request a feature?

• Support desk: support@crewlabs.io
• Response SLA: support requests are acknowledged within 24 business hours.