Create a webhook subscription

​

Receive all supported webhook events at a public HTTPS callback URL. Save the returned signingSecret to verify deliveries; later GET requests do not return it. Each event identifies the project, user or Design Help resource. Deleted users may no longer be fetchable. Custom header values are write-only; reads return their names. Deliveries may repeat or arrive out of order, so deduplicate by event ID. Reuse the Idempotency-Key and request body when retrying creation.

Headers

  • Unique for seven days. Reuse with the same body returns the original response.

Body

required
application/json
  • Public HTTPS URL that accepts signed POST requests from Artemis.

  • Webhook events your callback should receive.

    values
    • project-created
    • project-updated
    • design-help-started
    • design-help-ended
    • proposal-sent
    • contract-sent
    • contract-signed
    • contract-change-order-sent
  • Installer in your organization that owns the subscription.

  • Replace custom headers. Send an empty object to remove all custom headers. Values are write-only.

    Properties: 1
  • Whether the subscription is enabled.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for post/external/v2/webhook-subscriptions
curl https://sales-api.artemis.solar/external/v2/webhook-subscriptions \
  --request POST \
  --header 'Idempotency-Key: project-events-subscription-1' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_SECRET_TOKEN' \
  --data '{
  "callbackUrl": "https://integrations.example.com/webhooks/artemis",
  "eventTypes": [
    "project-created",
    "project-updated",
    "design-help-started",
    "design-help-ended"
  ],
  "installerId": "f7b7db62-29bf-4e70-bf73-a9221674f12a",
  "isActive": true
}'
Subscription created; save the signing secret
{
  "data": {
    "id": "79c336cf-4067-44af-af39-c235db33aae2",
    "callbackUrl": "https://integrations.example.com/webhooks/artemis",
    "callbackHasQuery": false,
    "apiMethod": "POST",
    "eventTypes": [
      "project-created",
      "project-updated",
      "design-help-started",
      "design-help-ended"
    ],
    "authType": "hmac",
    "hasAuthCredentials": true,
    "customHeaderNames": [],
    "isActive": true,
    "installerId": "f7b7db62-29bf-4e70-bf73-a9221674f12a",
    "contractVersion": 2,
    "createdAt": "2026-09-05T12:00:00.000Z",
    "updatedAt": "2026-09-05T12:00:00.000Z",
    "signingSecret": "example-only-replace-with-the-returned-signing-secret"
  }
}